No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Computer, Inc. Printed in the United States of America.
No licenses, express or implied, are granted with respect to any of the technology described in this book. Apple retains all intellectual property rights associated with the technology described in this book. This book is intended to assist application developers to develop applications only for Apple Macintosh computers.
Every effort has been made to ensure that the information in this manual is accurate. Apple is not responsible for printing or clerical errors.
Apple Computer, Inc.
1 Infinite Loop
Cupertino, CA 95014
408-996-1010
Apple, the Apple logo, APDA, AppleLink, AppleShare, AppleTalk, A/UX, EtherTalk, LaserWriter, Macintosh, MPW, PowerBook, ProDOS, and TokenTalk are trademarks of Apple Computer, Inc., registered in the United States and other countries.
Apple Desktop Bus, Apple SuperDrive, Balloon Help, Finder, ResEdit, Macintosh Quadra, PowerBook Duo, Power Macintosh, System 7, and QuickDraw, are trademarks of Apple Computer, Inc.
Motorola is a registered trademark of Motorola Corporation.
UNIX is a trademark of UNIX System Laboratories, Inc.
Simultaneously published in the United States and Canada.
LIMITED WARRANTY ON MEDIA AND REPLACEMENT
ALL IMPLIED WARRANTIES ON THIS MANUAL, INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE LIMITED IN DURATION TO NINETY (90) DAYS FROM THE DATE OF THE ORIGINAL RETAIL PURCHASE OF THIS PRODUCT.
Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS MANUAL IS SOLD “AS IS,” AND YOU, THE PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty.
Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.
1 The File System Manager
About this chapter
This chapter describes foreign file systems and the File System Manager (FSM). It also provides a complete description of all FSM data types, FSM service routines available to a foreign file system and other programs, and the FSM component interfaces.
About Foreign File Systems
A foreign file system allows Macintosh applications to gain access to non-Macintosh volumes using File Manager routines. For example, a Macintosh application can use File Manager routines to read from and write to files on a ProDOS disk if there is a foreign file system for ProDOS.
In the past, developing a foreign file system required extensive knowledge of the Macintosh File Manager and how it used both documented and undocumented low-memory global variables and data structures. To solve this problem, Apple has written the File System Manager. To create a new foreign file system, developers no longer need to access undocumented portions of the Macintosh and interface with the Macintosh file system through a 68000 register-based interface. Instead, they provide a foreign file system for a particular file system that works with the File System Manager. The File System Manager provides a systematic way for one or more foreign file systems to interact with the Macintosh file system using high-level language interface.
The File System Manager performs low-level tasks common to all foreign file systems. It intercepts incoming file system related traps, identifies the foreign file system the request should be passed to, and then passes on only those requests requiring action by the particular foreign file system. To develop a foreign file system, you provide a set of foreign file system routines—described in the following chapters—that the File System Manager can call.
Important Note: Even though the File System Manager provides many services that simplify development of foreign file systems, developing a foreign file system is both a difficult and time-consuming process. A minimal foreign file system must implement over forty Macintosh file system routines while a networked, sharable file system will have to implement as many as eighty Macintosh file system routines. To write a foreign file system you must be familiar with the low-level Macintosh file system data routines and data structures described in Inside Macintosh: Files and with the material covered in the chapters of the Guide to the File System Manager.
About the File System Manager
The File System Manager is the part of the Macintosh Operating System that manages the use of foreign file systems. The File System Manager provides a general means by which foreign file systems can be installed, identified, and interfaced to the Operating System .
The Operating System services provided by the File System Manager are called FSM components and the interface mechanism between an foreign file system and a particular FSM component is known as a FSM component interface. At this time, two FSM component interface are defined for use under the File System Manager
• the HFS Component Interface which allows a foreign file system to process File Manager requests
• the Disk Initialization Package Component Interface which allows foreign file systems to initialize foreign file system volumes on a Macintosh
For each installed file system, the File System Manager maintains a file system descriptor (FSD). Information in the FSD identifies the file system and describes its interfaces to the File System Manager and to the FSM component interfaces supplied by the File System Manager. Installed FSDs are kept in the File System Manager’s private FSD queue.
A foreign file system’s FSD can be installed, accessed, maintained, and removed with the FSM service routines. FSM service routines also allow applications to communicate with the File System Manager and foreign file systems, and allow disk drivers and foreign file systems to communicate with the File System Manager
Figure 1-1 shows how the Operating System and the File System Manager work together to allow applications to access foreign file systems.
Figure 1-1. Applications using foreign file systems through the File System Manager
Using the File System Manager
This section describes
• File system descriptors (FSDs)
• FSM component interfaces
• how to determine if the File System Manager is available
• how foreign file systems are installed and enabled
File System Descriptors
The File System Manager maintains a file system descriptor (FSD) for each installed foreign file system. Information in the FSD identifies the file system and describes its interfaces to the FSM component interfaces supplied by the File System Manager.
A foreign file system’s FSD is installed, accessed, maintained, and removed with the FSM service routines. FSDs are created with InstallFS. A copy of the information in an FSD can be obtained with GetFSInfo. Information in an FSD can be modified with SetFSInfo. An FSD can be removed with RemoveFS. The FSM service routines use the data type FSDRec.
struct FSDRec {
struct FSDRec *fsdLink; /* ptr to next */
short fsdLength; /* length of this FSD in
bytes */
short fsdVersion; /* version number */
short fileSystemFSID; /* file system id */
Str31 fileSystemName; /* file system name */
FSSpec fileSystemSpec; /* foreign file system's
FSSpec */
Ptr fileSystemGlobalsPtr; /* ptr to file system
globals */
FSDCommUPP fileSystemCommProc; /* communication proc with
the FFS */
long reserved3; /* reserved, must be 0 */
long reserved2; /* reserved, must be 0 */
long reserved1; /* reserved, must be 0 */
HFSCIRec fsdHFSCI; /* HFS component
interface */
DICIRec fsdDICI; /* Disk Initialization
component interface */
};
typedef struct FSDRec FSDRec;
typedef FSDRec *FSDRecPtr;
Field descriptions
fsdLink A pointer to the next entry in the FSD list.
fsdLength The length of of this FSD in bytes.
fsdVersion The lowest version of the File System Manager this foreign file system can support. Currently, this is 1.
fileSystemFSID The unique file system ID (FSID) of the foreign file system. See “File System ID Numbers” on page 1-7 for more information about FSID numbers.
fileSystemName A Pascal string (Str31) which is used to identify the foreign file system. It is not guaranteed to be unique. fileSystemName is used by the Disk Initialization Package. The name is displayed in a dialog box that presents the user a choice of file system formats with which a disk may be initialized.
fileSystemSpec An FSSpec indicating the location of the foreign file system’s file code file. The File System Manager fills in fileSystemSpec with the location of the current resource file (CurResFile) when the FSD is installed by InstallFS.
fileSystemGlobalsPtr A pointer to the foreign file system’s optional global data area. It is passed to the foreign file system as a parameter for all FSM component interface requests to the foreign file system. A nil value indicates no global area was allocated. The global data area is allocated by the foreign file system installation code.
fileSystemCommProc A pointer to the foreign file system’s communications function.
reserved3 Reserved. Must be zero.
reserved2 Reserved. Must be zero.
reserved1 Reserved. Must be zero.
fsdHFSCI The foreign file system’s HFS component interface record. See “The HFS Component Interface Record” in Chapter 2 for more information about the HFS component interface record.
fsdDICI The foreign file system’s Disk Initialization component interface record. See “The Disk Initialization Component Interface Record” in Chapter 4 for more information about the Disk Initialization component interface record.
File System ID Numbers
A file system ID (FSID) number is a unique word-length value that identifies a particular file system. This number is used by the Macintosh file system and by the File System Manager to identify a particular file system. The FSID value passed to InstallFS is checked by the File System Manager to insure that a FSD with that FSID is not already installed. The FSID is passed as a parameter to all File System Manager service routines. Table 1-1 is a list of file system IDs currently owned by Apple file systems.
Table 1-1. File System IDs owned by Apple file systems
FSID File System
$0000 Macintosh HFS or MFS
$0100 ProDOS File System
$0101 PowerTalk Mail Enclosures
$4147 ISO 9660 File Access (through Foreign File Access)
$4242 High Sierra File Access (through Foreign File Access)
$464D QuickTake File System (through Foreign File Access)
$4953 Macintosh PC Exchange (MS-DOS)
$4A48 Audio CD Access (through Foreign File Access)
$4D4B Apple Photo Access (through Foreign File Access)
FSID values between $0001 and $00FF are reserved for old-style foreign file systems that determine their FSID’s dynamically (i.e., by searching the drive queue) and cannot be used for File System Manager foreign file systems.
FSID values between $0100 and $7FFF are reserved for the File System Manager and other foreign file systems that use registered file system ID numbers.
FSID values $8000 and above are reserved for future use by Apple Computer, Inc.
FSID values fsmIgnoreFSID ($FFFE) and fsmGenericFSID ($FFFF) have special meaning. fsmIgnoreFSID is stored in the partition map on a partitioned disk. It signals the disk driver not to install this partition into the drive queue. fsmGenericFSID is stored in the drive queue element (DrvQEl) by the disk driver to signal an unknown foreign file system volume. The File System Manager will attempt to find a foreign file system that can identify disks with the fsmGenericFSID by calling each foreign file system with the ffsIDVolMountMessage message. This allows disk drivers to support multiple volume formats without having to identify the volume format.
To reserve a FSID in the File System Manager range ($0100 through $7FFF), a special creator type must be registered with Apple’s Developer Support Center (AppleLink: DEVSUPPORT). The high word of the creator type must be $0613. The low word of the creator type is the FSID to register. For example, to reserve the FSID $0100 for a foreign file system, the creator type $06130100 should be registered. The creator type registered for an FSID can also be used as the creator type of the system extension file that implements a foreign file system.
Important: File System ID numbers in the File System Manager range were not registered before 1993. As a result, there are foreign file systems in use that have not registered with Apple’s Developer Support Center. If you are the publisher of one of those foreign file systems, please register your FSID immediately to help prevent file system ID conflicts.
File System Communications Function
The communications function pointed to by fileSystemCommProc in an FSDRec is used by the File System Manager to communicate with a foreign file system. When the file system communications function is called, it is passed a message and a pointer to a buffer containing any additional parameters needed to process the message. The currently defined messages are listed in Table 1-2.
Table 1-2. File System Communications Function Messages
Message Purpose
ffsNopMessage 0 No operation. The file system communications function should simply return a result of noErr.
ffsGetIconMessage 1 Return disk icon and mask.
ffsIDDiskMessage 2 Identify the volume about to be mounted.
ffsLoadMessage 3 Load the foreign file system’s HFS component interface code and data.
ffsUnloadMessage 4 Unload the foreign file system’s HFS component interface code and data.
ffsIDVolMountMessage 5 Identify a VolMountInfo record by its media field.
ffsInformMessage 6 Foreign file system defined message.
The file system communications function is described in detail later in this chapter.
Global Data Area
Unlike a Macintosh application, a foreign file system possesses no A5 world. Therefore, a foreign file system cannot define and use global variables. Instead, the File System Manager allows a foreign file system to allocate a global data area which is used to store data needed globally by the foreign file system.
The global data area must be allocated in the system heap before the foreign file system is installed and the address of the global data area is stored in the foreign file system’s FSD. Every time the File System Manager calls a foreign file system function, the address of the global data area is passed to the foreign file system as one of the function parameters. This allows any part of a foreign file system to access the data in its global data area.
FSM Component Interfaces
The File System Manager supplies an interface mechanism known as an FSM component interface. An FSM component interface can be any functional interface exported by a given Macintosh operating system or toolbox component. Each FSM component interface is an independent interface, defined and managed by a particular Macintosh operating system or toolbox component. This includes the definition of the calls involved, the dispatching of calls to the foreign file systems, and the execution environment in which those calls operate.
At this time, two FSM component interfaces are defined for use under the File System Manager
• the HFS Component Interface which allows a foreign file system to process File Manager requests
• the Disk Initialization Package Component Interface which allows foreign file systems to initialize foreign file system volumes on a Macintosh
The FSD and the FSM component interface mechanism are both designed so that new FSM component interfaces can be added by Apple Computer to the File System Manager at a later time if needed.
The connection between a given component and a foreign file system is defined by a FSM component interface record which is contained in a foreign file system’s FSD. A minimum FSM component interface record includes a dispatch mask which controls the use of the interface, and at least one pointer to the foreign file system code responsible for processing the requests from that component. Additional interface parameters other than the dispatch mask and code pointer may be included in a given FSM component interface. These are FSM component interface dependent parameters and are not required by the File System Manager. These parameters are later used by the individual operating system or toolbox components to dispatch their requests to the foreign file system.
FSM Component Interface Dispatch Mask
The first long word of an FSM component interface record is the FSM component interface dispatch mask (compInterfMask). The bits of the compInterfMask currently have these meanings:
Bit Name Meaning
0-23 FSM component interface dependent flags. Each
component is free to define these flag bits
as needed.
24-29 Reserved for the File System Manager’s use.
30 fsmComponentBusyBit If set, the FSM component interface is busy (i.e.,
one or more requests are outstanding). This bit is
maintained by the component and used by the File
System Manager to control the use of the
SetFSInfo File System Manager service routine.
31 fsmComponentEnableBit If set, the component may begin dispatching
requests to the foreign file system. The foreign file
system should set this bit with the SetFSInfo
File System Manager service routine once it is
ready to receive requests.
FSM Component Interface Processing Function
The second long word of an FSM component interface record is a pointer (compInterfProc) to the foreign file system code responsible for processing redirected operating system or toolbox requests. Which operating system or toolbox requests are redirected is part of the FSM component interface definition.
FSM Component Interface Dispatching Conventions
In order to insure some degree of uniformity across FSM component interfaces, the File System Manager imposes some common conventions for use by components when dispatching requests to a foreign file system. Those conventions are
• The global pointer (fileSystemGlobalsPtr) from the FSD record is passed to the foreign file system on all requests. The global pointer is needed to locate context information associated with the operation of the foreign file system.
• The FSM component interface should dispatch requests to a foreign file system only if the fsmComponentEnableBit flag in the FSM component interface dispatch mask is set.
• The FSM component interface will set the fsmComponentBusyBit flag in the target file system’s FSM component interface dispatch mask when the interface is dispatched and clear the flag when the request has completed. This will prohibit modification of FSM component interface parameters by SetFSInfo.
Ensuring the File System Manager is Available
You must ensure the File System Manager is available on the user’s computer before calling the File System Manager. You can determine is the File System Manager is available by using the Gestalt function. The Gestalt selector is gestaltFSAttr. The File System Manager is available if the Gestalt function returns a result of noErr and the gestaltHasFileSystemManager bit is set in the response parameter.
In addition, you must ensure the File System Manager is version 1.2. Earlier versions of the File System Manager do not implement all of the interfaces described in this manual.
Listing 1-1 illustrates how you use Gestalt to determine if the File System Manager is available and ensure that the File System Manager is version 1.2 or later.
Listing 1-1. Testing for the required version of the File System Manager
static Boolean HasRequiredFSM(void)
{
long response;
Boolean result;
result = false;
/* Make sure the File System Manager is installed */
if ( Gestalt(gestaltFSAttr, &response) == noErr )
{
if ( (response & (1L << gestaltHasFileSystemManager)) != 0 )
{
/* We require File System Manager 1.1 features so */
/* check the version of FSM. */
if ( Gestalt(gestaltFSMVersion, &response) == noErr )
{
/* Make sure we have File System Manager 1.2 or later */
if ( (unsigned long)response >= 0x0120)
result = true;
}
}
}
return ( result );
}
Installing and Enabling a Foreign File System
Installation of foreign file systems will usually be accomplished by a system extension (INIT) file’s code at startup time. The mechanism that executes a system extension (commonly called the INIT 31 mechanism) is described in Chapter 29 “The System Resource File” in Inside Macintosh Volume IV, in Chapter 19 “The Start Manager” in Inside Macintosh Volume V, and in Inside Macintosh: Operating System Utilities. The INIT 31 mechanism will load and execute the foreign file system installation code in an 'INIT' resource in the foreign file system file.
The installation can also be done from within an application if precautions are taken to ensure the foreign file system is installed in the system heap, or if installed in the application’s heap, that all volume are unmounted and the foreign file system removed before the application quits.
If the File System Manager is available (see the section, Ensuring the File System Manager is Available) then the foreign file system installation code should install the foreign file system. To install a foreign file system, the foreign file system initialization code must allocate space for the global data area, load and detach the code resource for the FSM component interface processing function, initialize the fields of an FSDRec, and call InstallFS to add an FSD to the File System Manager’s FSD queue. If InstallFS is successful, the foreign file system is installed with its component interfaces disabled. Once the foreign file system is installed, the next step is to initialize the component interface records in the FSD to let the File System Manager know the features the foreign file system is capable of.
All foreign file systems must support the HFS component interface. To initialize the HFSCIRec in the FSD, the installation code should set the hfsCIDoesDynamicLoadMask bit in the compInterfMask field of the HFSCIRec. The File System Manager will call the fsdCommProc function with a ffsLoadMessage when it needs the foreign file system’s HFS component interface code loaded.
If the foreign file system supports the Disk Initialization component interface, then the installation code needs to load and detach the foreign file system’s disk initialization code and data, and then enable the Disk Initialization component interface in the FSD.
If the foreign file system is successfully installed, the installation code should call InformFSM with a fsmDrvQElChangedMessage message to mount any volumes owned by the foreign file system that might already be in drives.
File System Manager Service Routines
Six FSM service routines are provided by the File System Manager. These service routines let you install, access, maintain and remove the information in the FSDs, send the File System Manager messages, and send file system specific messages to a foreign file system. The FSM service routines are listed in Table 1-3.
Table 1-3. File System Manager Service Routines
Name Purpose
InstallFS Adds a new FSD to the File System Manager’s FSD queue.
RemoveFS Removes a FSD from the File System Manager’s FSD queue.
GetFSInfo Returns the FSD for a specific foreign file system or all foreign file systems.
SetFSInfo Changes the FSD information of a foreign file system.
InformFSM Sends messages or requests to the File System Manager.
InformFFS Sends a file system specific message to a foreign file system.
All of the FSM service routines execute synchronously. GetFSInfo and SetFSInfo may be called at any time. InstallFS, RemoveFS, and InformFSM cannot be called by code executing at interrupt time — they may make Memory Manager requests that move memory, or synchronous operating system requests. Note that the File System Manager service routines are not Macintosh file system routines and are not controlled by the file system queuing mechanism.
InstallFS
Use the InstallFS function to add a new file system descriptor to the system.
pascal short InstallFS (FSDRecPtr fsdPtr);
fsdPtr Contains a pointer to an FSDRec initialized with the data you want copied to the file system descriptor InstallFS creates in the FSD queue.
fsdPtr record
Æ fsdLength short Contains the size of the FSDRec.
Should always be sizeof(FSDRec).
Æ fsdVersion short Contains the minimum version of the
File System Manager this foreign file
system will work with. For the first
release, use fsdVersion1.
Æ fileSystemFSID short Contains the unique file system ID
(FSID) of the foreign file system.
Æ fileSystemName Str31 Conatins a Pascal string which is used
to identify the foreign file system by
name.
Æ fileSystemGlobalsPtr Ptr Contains a pointer to the foreign file
system’s optional global data area.
Æ fileSystemCommProc FSDCommUPP Contains a pointer to the foreign file
system’s communications function.
Æ reserved3 long Reserved field. Must be 0.
Æ reserved2 long Reserved field. Must be 0.
Æ reserved1 long Reserved field. Must be 0.
Æ fsdHFSCI HFSCIRec Contains the foreign file system’s HFS
component interface record.
Æ fsdDICI DICIRec Contains the foreign file system’s Disk
Initialization component interface
record.
The InstallFS function
• validates the FSDRec pointed to by fsdptr
• allocates a new file system descriptor
• copies the FSDRec pointed to by fsdptr to the new file system descriptor
• clears the fsdHFSCI and fsdDICI compInterfMask fields in the new file system descriptor
• initializes fileSystemSpec in the new file system descriptor to the location of the resource file referenced by CurResFile
• adds the new file system descriptor to the File System Manager’s FSD queue
Note that the FSDRec passed by fsdptr is only copied by InstallFS. The FSDRec passed by fsdptr does not become part of the File System Manager’s FSD queue.
Result codes
noErr 0 No error
fsmBadFFSNameErr -433 length of fsdPtr->fileSystemName is 0 or
greater than 31
fsmBadFSDLenErr -434 The file system descriptor is too large
(fsdPtr->fsdLength is greater than
sizeof(FSDRec))
fsmDuplicateFSIDErr -435 An FSD with fsdPtr->fileSystemFSID already
exists in FSD queue
fsmBadFSDVersionErr -436 fsdPtr->fsdVersion is greater than the
File System Manager version
memFullErr -108 The new file system descriptor could not be
allocated
RemoveFS
Use the RemoveFS function to remove file system descriptor from the File System Manager’s FSD queue.
pascal short RemoveFS (short fsid);
fsid Contains the unique file system ID (FSID) of the foreign file system.
RemoveFS removes the FSD specified by fsid from the File System Manager’s FSD queue and deallocates the memory allocated by the File System Manager for the file system descriptor. The file system descriptor can be removed only if all volumes owned by the foreign file system are unmounted and all FSM component interfaces in the file system descriptor are not busy.
Result codes
noErr 0 No error
fsmBusyFFSErr -432 A volume with the fsid is mounted or an
FSM component interfaces is busy
fsmFFSNotFoundErr -431 The file system descriptor with fsid was not
found in the FSD queue
GetFSInfo
Use the GetFSInfo function to get a copy of a file system descriptor in the File System Manager’s FSD queue.
pascal short GetFSInfo (short selector, short key, short *bufSize,
FSDRecPtr fsdptr);
selector Contains the method used to select the file system descriptor.
key Contains the key used to select the file system descriptor.
bufSize Contains a pointer to a short. On input, the field referred to by this parameter contains the size of the buffer pointed to by fsdPtr; on output, GetFSInfo places the number of bytes actually copied from the file system descriptor to the buffer into the field referred to by this parameter.
fsdPtr Contains pointer to a FSDRec. GetFSInfo copies the file system descriptor into the FSDRec referred to by this parameter.
The GetFSInfo function returns a copy of an file system descriptor in the FSD queue. The GetFSInfo function selects the file system descriptor according to these rules:
• If selector is fsmGetFSInfoByIndex, GetFSInfo returns returns a copy of the file system descriptor whose position in the FSD queue is specified by the key parameter. A key of 0 returns a copy of the first file system descriptor in the FSD queue.
• If selector is fsmGetFSInfoByFSID, GetFSInfo returns returns a copy of the file system descriptor whose File System ID is specified by the key parameter.
• If selector is fsmGetFSInfoByRefNum, GetFSInfo returns returns a copy of the file system descriptor using the volume or file reference number specified by the key parameter. The key parameter must be a valid file or volume reference number and must be a file or volume owned by a foreign file system installed by the File System Manager.
Result codes
noErr 0 No error
rfNumErr -51 The key was an invalid reference number or
referenced a volume not controlled by the
File System Manager
fsmFFSNotFoundErr -431 The file system descriptor with the FSID, or at
the specified index was not found in the
FSD queue
SetFSInfo
Use the SetFSInfo function to change a file system descriptor in the File System Manager’s FSD queue.
pascal short SetFSInfo (short fsid, short bufSize, FSDRecPtr fsdptr);
fsid Contains the unique file system ID (FSID) of the foreign file system.
bufSize Contains the size of the buffer pointed to by fsdPtr.
fsdPtr Contains a pointer to an FSDRec containing the data to be copied to the file system descriptor.
SetFSInfo changes the file system descriptor specified by the fsid parameter. This routine is normally used following InstallFS to enable the foreign file system’s component interfaces. bufSize bytes are copied to the file system descriptor from the buffer pointed to by fsdPtr. The fsdLink, fsdLength, fsdVersion, fileSystemFSID, fileSystemName, and fileSystemSpec fields in the file system descriptor are not modified by SetFSInfo.
Result codes
noErr 0 No error
fsmFFSNotFoundErr -431 The file system descriptor with fsid was
not found in the FSD queue
fsmBusyFFSErr -432 An FSM component interfaces is busy; the
file system descriptor cannot be modified
fsmBadFSDLenErr -434 The number of bytes specified by bufSize is
larger than the file system descriptor’s
fsdLength field
fsmNoAlternateStackErr -437 An attempt was made to enable the file system’s
HFS component interface but no alternate stack
was provided in fsdPtr->fsdHFSCI
InformFSM
Use the InformFSM function to communicate with the File System Manager.
pascal short InformFSM (short theMessage, void *paramBlock);
theMessage Contains the message to send to the File System Manager.
paramBlock Contains a pointer to optional message specific data.
InformFSM passes a message and optional message-specific data to the File System Manager. The File System Manager will return an fsmUnknownFSMMessageErr if an undefined message is passed. The currently defined messages are fsmNopMessage, fsmDrvQElChangedMessage, and fsmGetFSIconMessage. How the File System Manager handles each message and what result codes can be returned are described in the following paragraphs.
fsmNopMessage (0)
The File System Manager does nothing. The paramBlock parameter is ignored and the result is always noErr.
Result codes
noErr 0 No error
fsmDrvQElChangedMessage (1)
The fsmDrvQElChangedMessage tells the File System Manager to search the drive queue for unmounted volumes and attempt to find a File System Manager controlled foreign file system that can mount the volume. If a foreign file system is found that can mount the volume, the File System Manager will issue a diskInsertEvt for the drive so the foreign file system can mount the volume.
Note: Drive queue elements with the value fsmIgnoreFSID in the dQFSID field are ignored by the File System Manager when it searches for unmounted volumes.
This message can be sent by a disk driver to notify the File System Manager that a unmounted disk has a non-HFS partition. Before sending this message, the disk driver has allocated a drive queue element for the partition and added it to the system’s drive queue.
This message is also sent by a foreign file system’s installation code to check for unmounted disks after a foreign file system is installed.
The paramBlock parameter is ignored. The result is always noErr.
Note: This message can cause memory to move. A disk driver can safely make this request only at driver accRun time.
Result codes
noErr 0 No error
fsmGetFSIconMessage (2)
The fsmGetFSIconMessage tells the File System Manager to get a foreign file system’s disk icon. The paramBlock parameter points to a FSMGetIconRec.
FSMGetIconRec
Æ refNum short Contains the target drive number, volume
reference number, or working directory
number
Æ iconBufferPtr Ptr Contains a pointer to the icon buffer where the
foreign file system will return the icon data
Æ requestSize long Contains the size of the supplied icon buffer
¨ actualSize long The foreign file system returns the actual size
of the icon data in this field
Æ iconType char Contains the kind of icon requested
¨ isEjectable Boolean The File System Manager returns true in this
field if the device is ejectable
¨ driveQElemPtr DrvQElPtr The File System Manager returns a pointer to
the drive’s DrvQEl in this field
¨ fileSystemSpecPtr FSSpecPtr The File System Manager returns a pointer to
foreign file system’s FSSpec in this field
Æ reserved1 long reserved, must be zero
The refNum field must contain the target drive number, volume reference number or working directory number. The iconBufferPtr field must point to the buffer where the icon will be returned. The requestSize field must contain the size of the supplied icon buffer. The iconType field must contain the kind of icon requested.
The icon kinds supported and their sizes are those used by the Desktop Manager and are listed in Table 1-4.
Table 1-4. Icon Types
Value or
bytes in Corresponding
Constant bitmap resource type Description
kLargeIcon
kLarge4BitIcon
kLarge8BitIcon
kSmallIcon
kSmall4BitIcon
kSmall8BitIcon 1
2
3
4
5
6 'ICN#'
'icl4'
'icl8'
'ics#'
'ics4'
'ics8' Large black & white icon w/mask
Large 4-bit color icon
Large 8-bit color icon
Small black-and-white icon w/mask
Small 4-bit color icon
Small 8-bit color icon
kLargeIconSize
kLarge4BitIconSize
kLarge8BitIconSize
kSmallIconSize
kSmall4BitIconSize
kSmall8BitIconSize 256
512
1024
64
128
256 'ICN#'
'icl4'
'icl8'
'ics#'
'ics4'
'ics8' Large black &white icon w/mask
Large 4-bit color icon
Large 8-bit color icon
Small black-and-white icon w/mask
Small 4-bit color icon
Small 8-bit color icon
The File System Manager uses the refNum field in the FSMGetIconRec to determine the drive and the foreign file system that owns the drive. Then, the File System Manager fills in the isEjectable, driveQElemPtr, and fileSystemSpecPtr fields in the FSMGetIconRec and passes the FSMGetIconRec to the foreign file system with a ffsGetIconMessage message.
The foreign file system is responsible for returning the icon in the buffer pointed to by iconBufferPtr and the icon data size in the actualSize field. See the description of the file system communications function’s ffsGetIconMessage for more information.
Result codes
noErr 0 No error
nsvErr -35 refNum in FSMGetIconRec did not specify
a volume
nsDrvErr -56 refNum in FSMGetIconRec did not specify
a drive
afpItemNotFound -5012 The foreign file system could not return the
icon type requested
any of the result codes returned by FSpOpenResFile
InformFFS
Use the InformFFS function to communicate with foreign file systems through the File System Manager.
pascal short InformFFS(short fsid, void *paramBlock);
fsid Contains the unique file system ID (FSID) of the foreign file system.
paramBlock Contains a pointer to optional message specific data.
InformFFS passes a message through the File System Manager to the foreign file system specified by fsid. The message data structure is defined by each foreign file system.
Result codes
noErr 0 No error
fsmFFSNotFoundErr -431 The file system descriptor with fsid was
not found in the FSD queue
Foreign File System-Defined Routines
File System Communications Function
The communications function pointed to by fileSystemCommProc in an FSDRec is used by the File System Manager to communicate with a foreign file system. The fileSystemCommProc must have the following form.
message Contains the message being sent to the foreign file system.
paramBlock Contains a pointer to a buffer containing any additional parameters needed to process the message.
globalsPtr Contains a pointer to the foreign file system’s optional global data area.
When the file system communications function is called, it is passed a message and a pointer to a buffer containing any additional parameters needed to process the message. The currently defined messages are ffsNopMessage, ffsGetIconMessage, ffsIDDiskMessage, ffsLoadMessage, ffsUnloadMessage, ffsIDVolMountMessage, and ffsInformMessage. How the file system communications function should handle each message and what result codes should be returned are described in the following paragraphs. If the message passed is not recognized or handled by your file system communications function, the function result returned must be fsmUnknownFSMMessageErr (-438).
Note: The file system communications function is not called at interrupt time. Thus, it may make Memory Manager requests and synchronous operating system requests.
ffsNopMessage (0)
When the ffsNopMessage is passed to the file system communications function, do nothing and always return a result of noErr.
Result codes
noErr 0 No error
ffsGetIconMessage (1)
The ffsGetIconMessage is passed to the file system communications function when InformFSM is called with fsmGetFSIconMessage. The paramBlock parameter points to a FSMGetIconRec record.
FSMGetIconRec
Æ refNum short Contains the target drive number, volume
reference number, or working directory
number
Æ iconBufferPtr Ptr Contains a pointer to the icon buffer where the
foreign file system will return the icon data
Æ requestSize long Contains the size of the supplied icon buffer
¨ actualSize long The foreign file system returns the actual size
of the icon data in this field
Æ iconType char Contains the kind of icon requested
Æ isEjectable Boolean Contains true if the device is ejectable
Æ driveQElemPtr DrvQElPtr Contains a pointer to the drive’s DrvQEl
Æ fileSystemSpecPtr FSSpecPtr Contains a pointer to foreign file system’s
FSSpec
Æ reserved1 long reserved, must be zero
Your foreign file system uses iconType to determine the type of icon requested. If a known icon type is requested, open the foreign file system’s resource file (specified by fileSystemSpecPtr) with read-only access, get the specified icon resource, copy the icon data (up to requestSize bytes) into the buffer pointed to by iconBufferPtr, and then close the foreign file system’s resource file. Return the number of icon data bytes copied into into the buffer in the actualSize field.
Result codes
noErr 0 No error
afpItemNotFound -5012 The icon type requested could not be found
any of the result codes returned by FSpOpenResFile
ffsIDDiskMessage (2)
The ffsIDDiskMessage is passed to the file system communications function when the File System Manager intercepts a MountVol request. If the idSector field in the foreign file system’s HFSCIRec is not -1, the paramBlock parameter points to the disk block specified by the idSector field of the HFSCIRec. If the idSector field in the foreign file system’s HFSCIRec is -1, the paramBlock parameter points to the parameter block used to make the MountVol request and the ioVRefNum field in that parameter block contains the drive number of the volume to mount.
Your foreign file system should determine if the disk volume belongs to this foreign file system and return noErr if it does. If the disk volume cannot be identified, return extFSErr.
If your foreign file system returns noErr and its HFS component interface code is not loaded, the File System Manager will send your foreign file system a ffsLoadMessage.
Result codes
noErr 0 The disk volume belongs to this foreign file
system
extFSErr -58 The disk volume does not belong to this
foreign file system
ffsLoadMessage (3)
The ffsLoadMessage is passed to the file system communications function when the File System Manager needs to call the HFS component interface code of a foreign file system that is not loaded. The paramBlock parameter is not used.
You should check to see if the HFS component interface code is loaded. If not, load and detach the HFS component interface code and related data, allocate a stack for the HFS component interface code’s use, initialize the HFSCIRec in the FSD, set the hfsCIResourceLoadedBit in the compInterfMask, activate the HFS component interface for the foreign file system, and return noErr.
If the HFS component interface code cannot be loaded, the stack cannot be allocated, or the HFS component interface for the foreign file system cannot be activated, return an error result.
Result codes
noErr 0 No error; the HFS component interface was
successfully loaded and activated
memFullErr -108 The stack could not be allocated
any of the result codes returned by the Resource Manager, GetFSInfo, or SetFSInfo
ffsUnloadMessage (4)
The ffsUnloadMessage is passed to the file system communications function when the File System Manager no longer needs the HFS component interface code in memory. The paramBlock parameter is not used.
You should disable the HFS component interface, clear the hfsCIResourceLoadedBit in the compInterfMask, make the HFS component interface code and related data purgable, and dispose of the HFS component interface code’s stack.
Result codes
noErr 0 No error; the HFS component interface was
successfully unloaded and deactivated
any of the result codes returned by GetFSInfo, or SetFSInfo
ffsIDVolMountMessage (5)
This message is passed to the file system communications function when the File Manager’s VolumeMount routine is called to give a foreign file system a chance to claim the request. The paramBlock parameter points to parameter block used to make the VolumeMount request. The ioBuffer field of the parameter block points to a VolumeMountInfoHeader structure.
VolumeMountInfoHeader
Æ length short Contains the length in bytes of the entire VolumeMountInfo
record including this field and the variable length data
following the flags field
Æ media VolumeType Contains the VolumeType of the media to mount. This is the
creator type that you registered with Apple Computer, Inc. for
your file system ID number.
´ flags short Contains the volume mount flags.
Æ volMountInteractBit If set, it’s safe for the file system to
perform user interaction to mount
the volume
¨ volMountChangedBit If set, the file system mounted the
volume, but the volume mounting
information record needs to be
updated.
Note: The VolumeMountInfoHeader record is a superset of the VolMountInfoHeader record defined in Inside Macintosh: Files. In particular, the flags field used by the AppleShare file system was added to VolumeMountInfoHeader to allow foreign file systems to properly interact with the Alias Manager (the kARMNoUI rulesMask passed to MatchAlias is used to set or clear the volMountInteractBit; MatchAlias uses the volMountChangedBit to determine the value returned in the needsUpdate parameter).
You should compare the media field in the VolumeMountInfoHeader to your foreign file system’s media type and return noEr if they match. If they do not match, return extFSErr. Your media type should be the creator type assigned when you register your foreign file system’s FSID.
If your foreign file system returns noErr and its HFS component interface code is not loaded, the File System Manager will send your foreign file system a ffsLoadMessage.
Foreign file systems are called with the ffsIDVolMountMessage before the VolumeMount request is passed to the File Manager. If your foreign file system claims the request, it should use this time to load data or code resources and to perform any user interaction needed to mount the volume. User interface interactions should be performed only if the volMountInteract bit is set in the flags field. When the volMountInteract bit is set, it indicates the caller of VolumeMount has initialized the QuickDraw, the Font Manager, the Window Manager, the Menu Manager, TextEdit, and the Dialog Manager.
If the volume can be mounted and the foreign file system detemines the volume mounting information record needs to be updated, the foriegn file system should set the volMountChangedBit to indicate to the caller that it should call GetVolMountInfoSize and GetVolMountInfo to get an updated version of the volume mounting information record.
Note: When the foreign file system’s HFSCIProc is later called with the VolumeMount request, the foreign file system cannot call any system routines which might cause a File Manager request because the File Manager is single-threaded and not reentrant.
Result codes
noErr 0 The VolumeMount request belongs to this
foreign file system
extFSErr -58 The VolumeMount request does not belong to
this foreign file system
ffsInformMessage (6)
This message is passed to the file system communications function when InformFFS is called. The paramBlock parameter is the same paramBlock parameter passed to InformFFS.
The ffsInformMessage allows other programs to pass your foreign file system messages defined by you.
Result codes
noErr 0 No error
any result codes defined by your foreign file system for this request
2 The HFS Component Interface
About this chapter
This chapter describes the HFS component interface, the data structures used by the HFS component interface, and the routines your foreign file system must provide to the HFS component interface.
To use this chapter, you should be familiar with the information in the chapters “The File System Manager” and “File System Utility Routines” in this document, the information in Inside Macintosh: Files, and the information in Inside Macintosh: Devices.
About the HFS component interface
The HFS component interface allows a foreign file system to process File Manager requests and allows a foreign file system to describe its file system services to the File System Manager. Whenever a File Manager request is made to a volume controlled by a foreign file system, the File System Manager will pass that request to the foreign file system through the HFS component interface.
Using the HFS component interface
This section describes
• the HFS Component Interface record
• the foreign file system’s stack
• the HFS Component Interface request processing function
• the Logical to Physical function
• the Extend File function
The HFS Component Interface Record
The HFS component interface record in an File System Descriptor lets the foreign file system tell the HFS component interface how to dispatch file system requests to the foreign file system. It tells the HFS component interface where the routines to handle file system requests are in memory, what disk block the foreign file system needs to identify a disk, and where the foreign file system’s stack is. The data type HFSCIRec defines the HFS component interface record.
struct HFSCIRec {
long compInterfMask; /* component flags */
HFSCIUPP compInterfProc; /* pointer to file system
request processing code */
Lg2PhysUPP log2PhyProc; /* pointer to Lg2PhysProc */
Ptr stackTop; /* file system stack top */
long stackSize; /* file system stack
size */
Ptr stackPtr; /* current file system
stack pointer */
long reserved3; /* --reserved, must be
zero-- */
long idSector; /* Sector you need to ID a
local volume. For
networked volumes, this
should be -1. */
long reserved2; /* --reserved, must be
zero-- */
long reserved1; /* --reserved, must be
zero-- */
};
typedef struct HFSCIRec HFSCIRec;
typedef HFSCIRec *HFSCIRecPtr;
Field descriptions
compInterfMask Contains the HFS component interface dispatch mask. Currently the following bits are defined:
Bit Meaning
0-17 Reserved.
18 hfsCIHLL2PProcBit Set this bit if the log2PhyProc is
written in a high level language using
Pascal calling conventions. Note: this
bit should always be set by foreign
file systems using the logical to
physical interface described in this
chapter.
19 hfsCIResourceLoadedBit Set this bit if the HFSCIProc code
resource is loaded. If the foreign
file system doesn’t support dynamic
loading, this bit should always be
set.
20 hfsDoesDynamicLoadBit Set this bit if dynamically loading
code resource is supported.
21 hfsCIDoesDeskTopBit Set this bit if Desktop Manager
requests are supported. Obsolete, but
should be set. Current versions of
FSM always pass Desktop Manager
requests on to foreign file systems.
22 hfsCIDoesAppleShareBit Set this bit if AppleShare requests are
supported. Obsolete, but should
be set. Current versions of FSM
always pass AppleShare requests on
to foreign file systems.
23 hfsCIDoesHFSBit Set this bit if HFS requests are
supported. Obsolete, but should
be set. Current versions of FSM
always pass HFS requests on to
foreign file systems.
24-29 Reserved for the File System
Manager’s use.
30 fsmComponentBusyBit If set, the FSM component interface
is busy (i.e., one or more requests are
outstanding). This bit is maintained
by the component and used by the
File System Manager to control the
use of the SetFSInfo File System
Manager service routine.
31 fsmComponentEnableBit If set, the component may begin
dispatching requests to the foreign file
system. The foreign file system
should set this bit with the
SetFSInfo File System Manager
service routine once it is ready to
receive requests.
compInterfProc Contains a pointer to the foreign file system’s HFS component interface request processing function .
log2PhyProc Contains a pointer to the foreign file system’s Logical to Physical routine.
stackTop Contains a pointer to the top of the foreign file systems’s stack. stackTop must be word aligned value since it becomes the stack pointer whenever the foreign file systems is called.
stackSize Contains the size of the foreign file systems’s stack.
stackPtr Reserved for future use by the File System Manager.
reserved3 Reserved, must contain zero.
idSector Contains the sector the foreign file system needs to identify a local volume, or contains -1 if a network foreign file system. When the file system communications function is called with ffsIDDiskMessage and idSector is not -1, the paramBlock parameter points to the disk block specified. When the file system communications function is called with ffsIDDiskMessage and idSector is -1, the paramBlock parameter points to the parameter block used to make the MountVol request and the ioVRefNum field in that parameter block contains the drive number of the volume to mount.
reserved2 Reserved, must contain zero.
reserved1 Reserved, must contain zero.
The Foreign File System’s Stack
Each foreign file system must have its own alternate stack. The File System Manager’s HFS component interface saves the original application stack and switches to the foreign file system’s alternate stack before calling the foreign file system’s request processing function. After the foreign file system services the File Manager request, The File System Manager’s HFS component interface switches back to the original application stack.
If the foreign file system performs I/O through the File System Utility cached I/O routines, there will be an additional stack switch while the HFS file system handles the I/O. Foreign file system Logical to Physical routines run on the foreign file system’s stack.
The foreign file system’s alternate stack must be allocated in the system heap with NewPtrSys before the HFS component interface is activated. If the foreign file system supports dynamically loading code resources, the stack can be allocated when the file system communications function is called with the ffsLoadMessage and released when the file system communications function is called with the ffsUnloadMessage.
The size of a foreign file system’s alternate stack should be the amount needed by your foreign file system plus two or three kilobytes of additional space for use by interrupt driven processes which may borrow space at interrupt time from your stack.
The HFS Component Interface Request Processing Function
The HFS Component Interface request processing function pointed to by compInterfProc in a HFSCIRec is called by the File System Manager to handle File Manager requests. The HFS Component Interface request processing function must have the following form.
pascal OSErr HFSCIProc(VCBPtr theVCB, short selectCode,
void *paramBlock, void *fsdGlobalPtr,
short fsid);
theVCB Contains a pointer to the VCB of the volume that is the target of the file system request.
selectCode Contains either the A-Trap number or the HFSDispatch selector number which indicates what file system request was made.
paramBlock Contains a pointer to the parameter block passed to the file system request.
fsdGlobalPtr Contains a pointer to the foreign file system’s optional global data area.
fsid Contains the file system ID number of the volume.
When a foreign file system’s HFSCIProc is called, it is told which volume (theVCB) is the target of the file system request (except for MountVol and VolumeMount as explained later in this section), what file system request was made, and is passed the parameter block used to make the file system request. The foreign file system should handle the request, fill in the appropriate fields in the parameter block, and return the appropriate result. The File System Manager provides File System Utility routines to your foreign file system to help it process file system request.
s Warning: When the foreign file system’s HFSCIProc is called, the foreign file system cannot do anything which might cause another File Manager request because the File Manager is single-threaded and is not reentrant. If your foreign file system’s HFSCIProc does cause another File Manager request, the Macintosh system will deadlock. s
The HFSCIProc is also passed a pointer to the foreign file system’s global data area and the file system ID number of the volume. The file system ID number allows a foreign file system that handles multiple file systems to quickly determine which file system needs to handle the file system request.
Result codes
noErr 0 The foreign file system handled the Macintosh
file system request with no errors
any of the result codes documented for a particular Macintosh file system request in Inside Macintosh: Files
Listing 2-1 is an abbreviated example of a request processing function. Not all HFSDispatch selectors and Macintosh file system A-Traps are shown in this example.
Listing 2-1. HFS Component Interface request processing function
/* Prototype for file system request handler routine */
typedef OSErr (*hfsProcPtr)(VCBPtr theVCB, short selectCode,
void *paramBlock, void *fsdGlobalPtr,
short fsid);
pascal OSErr HFSCIProc (VCBPtr theVCB, short selectCode,
void *paramBlock, void *fsdGlobalPtr,
short fsid)
{
OSErr result = extFSErr;
hfsProcPtr hfsProc;
unsigned short trapWord;
/* selectCode contains the trap word or HFSDispatch selector */
/* Clear the trap attributes (i.e., async and immediate bits) */
trapWord = selectCode & 0xF0FF;
/* and find out what to call with the big, big switch statement... */
switch (trapWord)
{
/* HFSDispatch (A260) file system selectors */
case kFSMOpenWD:
hfsProc = DoOpenWD;
break;
/*
** The rest of HFSDispatch (A260) file system selectors go here.
** The rest of HFSDispatch (A260) Desktop Manager selectors
** go here.
*/
case kFSMDTDelete:
hfsProc = DoDTDelete;
break;
/* HFSDispatch (A260) AppleShare selectors */
case kFSMGetVolParms:
hfsProc = DoGetVolParms;
break;
/*
** The rest of HFSDispatch (A260) AppleShare selectors
** go here.
*/
case kFSMSetForeignPrivs:
hfsProc = DoSetForeignPrivs;
break;
/* File system A-traps */
case kFSMOpen:
hfsProc = DoOpen;
break;
/*
** The rest of File system A-traps go here.
*/
case kFSMFlushFile:
hfsProc = DoFlushFile;
break;
/* and if it wasn't there... */
default:
hfsProc = DoRequestNotSupported;
break;
}
/* Call the appropriate file system request handler routine */
result = hfsProc(theVCB, selectCode, paramBlock, fsdGlobalPtr, fsid);
return(result);
}
Handling MountVol and VolumeMount requests
There are two File Manager requests sent to a foreign file system’s HFSCIProc that may or may not be handled by your foreign file system, MountVol (selectCode = $A00F) and VolumeMount (selectCode = $0041). The File System Manager sends those requests to each installed foreign file system until one of the foreign file systems indicates that it has handled the request.
If your foreign file system receives a MountVol request, it must determine if the disk volume belongs to it. You may be able to use the same code your foreign file system used to handle the ffsIDDiskMessage is passed to the file system communications function. If the volume is not your volume, you must return extFSErr. If the volume is your volume, you must return noErr if you successfully mount the volume, or one of the error result codes listed for PBMountVol in Inside Macintosh: Files.
If your foreign file system receives a VolumeMount request and supports the VolumeMount related selectors (VolumeMount, GetVolMountInfoSize, and GetVolMountInfo), it should compare the media field in the VolumeMountInfoHeader to your foreign file system’s media type. If the media field does not match your media type, return extFSErr. If the media field matches your media type, you must return noErr if you successfully mount the volume, or one of the error result codes listed for PBVolumeMount in Inside Macintosh: Files. If your foreign file system does not support the VolumeMount related selectors, it should return paramErr.
The Logical to Physical Block Mapping Function
The Macintosh cache routines described in “File System Utility Routines” chapter can read or write either logical blocks of a file or physical blocks of a volume. However, because disk driver device requests always read or write physical blocks of a volume, a foreign file system must provide a routine to map logical file blocks to physical volume blocks. That routine is called the logical to physical routine. The address of the logical to physical routine is passed to the File System Manager in the log2PhyProc field of the foreign file system’s HFSCIRec and as a parameter to some cache routines. The logical to physical routine must have the following form.
pascal OSErr Lg2PhysProc(void *fsdGlobalPtr,
VCBPtr volCtrlBlockPtr,
FCBRecPtr fileCtrlBlockPtr,
short fileRefNum,
unsigned long filePosition,
unsigned long reqCount,
unsigned long *volOffset,
unsigned long *contiguousBytes);
fsdGlobalPtr Contains a pointer to the foreign file system’s optional global data area.
volCtrlBlockPtr Contains a pointer to the file’s Volume Control Block (VCB).
fileCtrlBlockPtr Contains a pointer to the file’s File Control Block (FCBRec) that is the target of the logical to physical mapping.
fileRefNum Contains the file’s reference number.
filePosition Contains the byte offset into the file’s data where the mapping should begin (always a multiple of 512 bytes).
reqCount Contains the number of bytes requested for the mapping operating (always a multiple of 512 bytes).
volOffset Contains a pointer to an unsigned long. Lg2PhysProc places the offset (in bytes) to the volume block where the file data can be found into the field referred to by this parameter. The value returned must be a multiple of 512 bytes.
contiguousBytes Contains a pointer to an unsigned long. Lg2PhysProc places the number of contiguous bytes which occur after the given offset, up to requestCount, into the field referred to by this parameter. The value returned must be a multiple of 512 bytes.
It is the responsibility of the foreign file system to return an eofErr when a request for data is beyond the current logical end of file (before calling the Cache utility routines). It is the responsibility of the logical to physical routine to return an eofErr error when a cache routine asks for block mapping beyond the current physical end of file.
Result codes
noErr 0 Logical to physical mapping was successful
eofErr -39 Requested mapping was beyond the
physical end of file
ioErr -36 Mapping failed because of an unexpected error
Here is a brief description of how logical to physical mapping works. Assume that a file is open and that file occupies the physical blocks 101 through 103 and 105 through 109 (8 disk blocks) on the disk volume. The logical to physical routine needs to map bytes 0 through 1535 to blocks 101 through 103 and map bytes 1536 through 8191 to blocks 105 through 109. Here’s an example of how a logical to physical routine would perform the job of mapping a read to the fragmented file.
A Read request is recieved through the HFSCIProc asking for 3072 bytes starting at offset 0 in the file. The HFSCIProc calls the file system’s Read request hander routine which eventually calls UTCacheReadIP to read the data from the file. The first time UTCacheReadIP is called, the Macintosh cache mechanism calls your logical to physical routine with filePosition = 0 and reqCount = 3072. The logical to physical routine returns 51712 in volOffset (the byte offset of block 101) and 1536 in contiguousBytes (the number of contiguous bytes starting at offset 51712 ). The Macintosh cache mechanism will then read 1536 bytes starting at offset 51200 into the buffer passed to UTCacheReadIP.
Since the Read request hasn’t been satisfied, the file system’s Read request hander routine updates the buffer pointer and calls UTCacheReadIP again - this time asking for 1536 bytes starting at offset 1536 in the file. The Macintosh cache mechanism calls your logical to physical routine with filePosition = 1536 and reqCount = 1536. The logical to physical routine returns 53760 in volOffset (the byte offset of block 105) and 1536 in contiguousBytes (the number of contiguous bytes starting at offset 53760 ). The Macintosh cache mechanism will then read 1536 bytes starting at offset 53760 into the buffer passed to UTCacheReadIP and the Read request is complete.
3 The File System Utility Routines
About this chapter
This chapter describes the utility routines provided by the File System Manager to your foreign file system to help it process Macintosh file system calls and describes the data structures used by the Macintosh file system.
To use this chapter, you should be familiar with the information in the chapter “The HFS Component Interface” in this document, the information in Inside Macintosh: Files, and the information in Inside Macintosh: Devices.
About File System Utility Routines
The File System Utility routines are intended for use by foreign file systems to allow your foreign file system to
• access file control blocks (FCBs), volume control blocks (VCBs), working directory control blocks (WDCBs), and drive queue elements (DrvQEl)
• set and get the default volume and working directory
• eject a volume
• validate and process parameters passed with Macintosh file system calls
• access the Macintosh file system’s cache buffers and low-level I/O services
s Warning: File System Utility routines that can cause I/O through the Macintosh file system’s cache, UTGetBlock, UTReleaseBlock, UTFlushCache, UTCacheReadIP, and UTCacheWriteIP, must be called from a foreign file system handling a request through its HFSCIProc. Attempts to call those routines outside of the context of the HFSCIProc will cause a system crash. s
Macintosh File System Data Structures
This section describes the data structures used internally by the Macintosh file system. Foreign file systems need to access and manipulate these data strutures when handling calls from the HFS component interface.
The data structures include
• volume control blocks (VCBs)
• file control blocks (FCBs)
• working directory control blocks (WDCBs)
• drive queue elements (DrvQEl)
The data structures (except for working directory control blocks) and their use are described in Inside Macintosh: Files. The following sections describe how foreign file systems should use them.
Volume Control Blocks
Each time a volume is mounted, a foreign file system must allocate a volume control block (VCB) with UTAllocateVCB, read the volume and use the information to initialize the fields in the new VCB, and add the VCB to the VCB queue with UTAddNewVCB (unless an ejected or offline volume is being remounted). When a volume is unmounted, its VCB is removed from the VCB queue UTDisposeVCB.
The volume control block queue is a standard Operating System queue maintained in the system heap. It contains a volume control block for each mounted volume. A volume control block is a nonrelocatable block that contains volume-specific information. If your foreign file system needs to keep additional information beyond that kept in the system VCB structure, you can allocate additional memory with UTAllocateVCB for your extended VCB structure. The structure of a system volume control block is defined by the VCB data type.
struct VCB { /* volume control block */
QElemPtr qLink; /* next queue entry */
short qType; /* queue type */
short vcbFlags; /* volume flags */
unsigned short vcbSigWord; /* volume signature */
unsigned long vcbCrDate; /* date and time of volume
creation */
unsigned long vcbLsMod; /* date and time of last
modification
short vcbAtrb; /* volume attributes */
unsigned short vcbNmFls; /* number of files in root
directory */
short vcbVBMSt; /* first block of volume
bitmap */
short vcbAllocPtr; /* start of next allocation
search */
unsigned short vcbNmAlBlks; /* number of allocation blocks
in volume */
unsigned long vcbAlBlkSiz; /* size (in bytes) of
allocation blocks
unsigned long vcbClpSiz; /* default clump size */
short vcbAlBlSt; /* first allocation block in
volume */
long vcbNxtCNID; /* next unused catalog node
ID */
unsigned short vcbFreeBks; /* number of unused allocation
blocks */
Str27 vcbVN; /* volume name */
short vcbDrvNum; /* drive number */
short vcbDRefNum; /* driver reference number */
short vcbFSID; /* file-system identifier */
short vcbVRefNum; /* volume reference number */
Ptr vcbMAdr; /* used internally */
Ptr vcbBufAdr; /* used internally */
short vcbMLen; /* used internally */
short vcbDirIndex; /* used internally */
short vcbDirBlk; /* used internally */
unsigned long vcbVolBkUp; /* date and time of last
backup */
unsigned short vcbVSeqNum; /* volume backup sequence
number */
long vcbWrCnt; /* volume write count */
long vcbXTClpSiz; /* clump size for extents
overflow file */
long vcbCTClpSiz; /* clump size for catalog
file */
unsigned short vcbNmRtDirs; /* number of directories in
root dir */
long vcbFilCnt; /* number of files in
volume */
long vcbDirCnt; /* number of directories in
volume */
long vcbFndrInfo[8]; /* information used by the
Finder */
unsigned short vcbVCSize; /* used internally */
unsigned short vcbVBMCSiz; /* used internally */
unsigned short vcbCtlCSiz; /* used internally */
unsigned short vcbXTAlBlks; /* size of extents overflow
file */
unsigned short vcbCTAlBlks; /* size of catalog file */
short vcbXTRef; /* ref. num. for extents
overflow file */
short vcbCTRef; /* ref. num. for catalog
file */
Ptr vcbCtlBuf; /* ptr. to extents and catalog
caches */
long vcbDirIDM; /* directory last searched */
short vcbOffsM; /* offspring index at last
search */
};
typedef struct VCB VCB;
typedef VCB *VCBPtr;
Field descriptions
qLink A pointer to the next entry in the VCB queue. This field is initialized when the VCB is added to the VCB queue by UTAddNewVCB.
qType The queue type. This field is initialized when the VCB is added to the VCB queue by UTAddNewVCB.
vcbFlags Volume flags. Set bit 15 if the volume information has been changed by a File Manager call since the volume was last affected by a FlushVol call.
vcbSigWord The volume signature. This field must be set to $4244.
vcbCrDate Set to the date and time of volume creation (initialization), specified as the number of seconds since midnight, January 1, 1904.
vcbLsMod Set to the date and time of last modification, specified as the number of seconds since midnight, January 1, 1904. This is not necessarily when the volume was last flushed.
vcbAtrb Volume attributes. The bits have these meanings:
Bit Meaning
0–5 Reserved.
6 Set this bit if the volume is busy (one or more files are
open).
7 Set this bit if the volume is locked by hardware. This can
be obtained when the volume is mounted with the
DriveStatus function.
8–14 Reserved.
15 Set this bit if the volume is locked by software. This bit
can be set or cleared by programs calling your foreign
file system with _SetVInfo and you should store it
between volume mounts.
vcbNmFls Set to the number of files in the volume’s root directory.
vcbVBMSt For HFS volumes, this field is used to point to the first block of the volume bitmap. Your foreign file system can use this field to point to an analogous structure. If it doesn’t, the field’s value must be 0.
vcbAllocPtr For HFS volumes, this field is used to point to the start block of the next allocation search. Your foreign file system can use this field for a similar purpose. If it doesn’t, the field’s value must be 0.
vcbNmAlBlks Set to the number of allocation blocks in the volume (maximum $FFFF).This field, together with the vcbAlBlkSiz field, is used to determine the number of bytes on a particular volume. It must be initialized to a value which when multiplied with vcbAlBlkSiz provides a reasonable estimate of the size of the disk.
vcbAlBlkSiz Set to the allocation block size (in bytes). This field, together with the vcbNmAlBlks field, is used by the Finder and other applications to determine the number of bytes on a particular volume. It must be initialized to some non-zero multiple of 512.
vcbClpSiz Set to the default clump size. For HFS volumes, this field is used to determine how many new allocation blocks to allocate when the file is extended. Your foreign file system can use this field for the same purpose, but in any case, it must set its value to a multiple of vcbAlBlkSiz or 0.
vcbAlBlSt Set to the first allocation block in the volume. For HFS volumes, this is the number of the first block used for files. If your foreign file system has an analogous structure (that is, if its header blocks are followed by a contiguous set of blocks for files), it can use this field in the same way. If not, it must leave this field zero.
vcbNxtCNID The next unused catalog node ID (directory ID or file ID). For HFS volumes, this is set to fsUsrCNID when the volume is initialized. When a new directory or file is created, vcbNxtCNID is used as the directory ID or file ID and then incremented. Your foreign file system can use this field for the same purpose, or may leave it zero.
vcbFreeBks Set to the number of unused allocation blocks on the volume (maximum $FFFF). This field, together with vcbAlBlkSiz, is used by the Finder and other applications to determine the number of free bytes in the volume. It must be initialized to a value which when multiplied with vcbAlBlkSiz provides a reasonable estimate of the free space in the volume.
vcbVN Set to the volume name. This field consists of a length byte followed by 27 bytes. Note that the volume name can occupy at most 27 characters; this is an exception to the normal file and directory name limit of 31 characters. The volume name must conform to the rules for HFS volumes (i.e., no colon characters). For file systems that have no volume-naming conventions, some standard name (such as “Untitled”) must be provided.
vcbDrvNum The drive number of the drive on which the volume is located. This field is initialized when the VCB is added to the VCB queue by UTAddNewVCB. When a mounted volume is placed offline or ejected, vcbDrvNum is set to 0.
vcbDRefNum The driver reference number of the driver used to access the volume. This field is initialized when the VCB is added to the VCB queue by UTAddNewVCB. When a volume is ejected, vcbDRefNum is set to the previous value of vcbDrvNum (and hence is a positive number). When a volume is placed offline, vcbDRefNum is set to the negative of the previous value of vcbDrvNum (and hence is a negative number).
vcbFSID An identifier for the file system handling the volume; it is zero for volumes handled by the File Manager and nonzero for volumes handled by other file systems. Set to your foreign file system’s file system ID.
vcbVRefNum The volume reference number. This field is initialized when the VCB is added to the VCB queue by UTAddNewVCB.
vcbMAdr Used internally. Reserved.
vcbBufAdr Used internally. Reserved.
vcbMLen Used internally. Reserved.
vcbDirIndex Used internally. Reserved.
vcbDirBlk Used internally. Reserved.
vcbVolBkUp Set to the date and time of the last volume backup, specified as the number of seconds since midnight, January 1, 1904.
vcbVSeqNum Used internally. Reserved.
vcbWrCnt The volume write count. This field is incremented every time the volume is written to by the Macintosh file system’s cache. If your foreign file system uses the Macintosh file system’s cache, it must either initialize this field to zero when a volume is mounted, or it must initialize this field to zero the first time the volume is mounted and then save the current value of this field when a volume is unmounted and restore the value when the volume is mounted again to keep a running count of writes to the volume.
vcbXTClpSiz The clump size of the extents overflow file. Reserved.
vcbCTClpSiz The clump size of the catalog file. Reserved.
vcbNmRtDirs Set to the number of directories in the root directory or leave it zero.
vcbFilCnt Set to the number of files on the volume or leave it zero.
vcbDirCnt Set to the number of directories on the volume (not including the root directory) or leave it zero.
vcbFndrInfo Information used by the Finder. For HFS volumes, this field is used internally by HFS. Leave it all zeroes until set by _SetVInfo.
vcbVCSize Used internally. Reserved.
vcbVBMCSiz Used internally. Reserved.
vcbCtlCSiz Used internally. Reserved.
vcbXTAlBks The size (in blocks) of the extents overflow file. Reserved.
vcbCTAlBks The size (in blocks) of the catalog file. Reserved.
vcbXTRef The path reference number for the extents overflow file. Reserved.
vcbCTRef The path reference number for the catalog file. Reserved.
vcbCtlBuf A pointer to the extents and catalog caches. Reserved.
vcbDirIDM The directory last searched. For HFS volumes, this field is used internally by HFS to optimize GetCatInfo and GetFInfo. Your foreign file system can use this field for the same purpose, or may leave it zero.
vcbOffsM The offspring index at the last search. For HFS volumes, this field is used internally by HFS to optimize GetCatInfo and GetFInfo. Your foreign file system can use this field for the same purpose, or may leave it zero.
There are also three File System Utility routines that let you search the VCB queue
• UTLocateVCBByRefNum searches for the VCB using a working directory number, volume reference number, or drive number
• UTLocateVCBByName searches for the first VCB with a volume name
• UTLocateNextVCB searches the VCB queue for the next VCB with the volume name passed to UTLocateVCBByName (the Macintosh file system allows multiple mounted volumes to have the same volume name)
Maximum Volume and File Sizes
The maximum volume size supported by the current File Manager programming interface is slightly less than 4 Gigabytes. The exact number is the maximum allocation block size ($FE00) multiplied by the maximum number of allocation blocks ($FFFF) — that’s $FDFF0200 or 4261347840 decimal. To access volumes 2 Gigabytes or larger (larger than $7FFFFFFF or 2147483647 decimal), your foreign file system must used unsigned longword values when determining volume offsets and disk drivers called by your foreign file system must assume that the position passed to Read and Write requests in ioPosOffset is an unsigned longword value.
However, many applications, including versions of the Macintosh Finder, use signed longword values when determining volume size and volume freespace. Because of this, volumes 2 Gigabytes or larger may cause unexpected behavior.
Starting with System 7.5, the Macintosh Finder has been changed to use unsigned longword values when determining volume size and volume freespace. The File Manager routine PBHGetVInfo has also been changed starting with System 7.5 to pin the number of allocation blocks (vcbNmAlBlks) and the number of free allocation blocks (vcbNmAlBlks) so that when multiplied by the allocation block size (vcbAlBlkSiz), the result will be less than 2 Gigabytes. This prevents unexpected behavior from other applications that use signed longwords when determining volume size and volume freespace. The values in the VCB fields vcbNmAlBlks and vcbNmAlBlks are not changed. Listing 3-1 illustrates how you use Gestalt to determine if 4 Gigabyte volumes are supported by the Macintosh operating system.
Listing 3-1. Testing for 4 Gigabyte volume support
The maximum file size supported by the current File Manager programming interface is 2 Gigabytes - 1 byte ($7FFFFFFF or 2147483647 decimal) because File Manger Read and Write requests use ioPosOffset as a signed longword value.
File Control Blocks
Each time a file is opened on a volume owned by a foreign file system, the foreign file system must read that file’s catalog entry and build a file control block (FCB) in the FCB array. A new FCB is obtained with the UTAllocateFCB function.
When a file is closed, the foreign file system must mark the FCB free and release it with the UTReleaseFCB function.
The structure of a file control block is defined by the FCBRec data type.
struct FCBRec {
unsigned long fcbFlNm; /* FCB file number. Non-zero
marks FCB used */
SignedByte fcbFlags; /* FCB flags */
SignedByte fcbTypByt; /* File type byte */
unsigned short fcbSBlk; /* File start block (in
allocation size blocks) */
unsigned long fcbEOF; /* Logical length or EOF in
bytes */
unsigned long fcbPLen; /* Physical file length in
bytes */
unsigned long fcbCrPs; /* Current position within
file */
VCBPtr fcbVPtr; /* Pointer to the
corresponding VCB */
Ptr fcbBfAdr; /* File's buffer address */
unsigned short fcbFlPos; /* Directory block this file
is in */
unsigned long fcbClmpSize; /* Number of bytes per
clump */
Ptr fcbBTCBPtr; /* Pointer to B*-Tree control
block for this file */
unsigned long fcbExtRec[3]; /* First 3 file extents */
OSType fcbFType; /* File's 4 Finder Type
bytes */
unsigned long fcbCatPos; /* Catalog hint for use on
Close */
unsigned long fcbDirID; /* Parent Directory ID */
Str31 fcbCName; /* CName of open file */
};
typedef struct FCBRec FCBRec;
typedef FCBRec *FCBRecPtr;
Field descriptions
fcbFlNum Set to the file ID of this file. File numbers less than fsUsrCNID are considered system files.
fcbFlags Flags describing the status of the file. Currently the following bits are defined:
Bit Meaning
0 fcbWriteBit Set if data can be written to the file
1 fcbResourceBit Set if this FCB describes a resource fork
2 fcbWriteLockedBit Set if the file has a locked byte range
3 Reserved
4 fcbSharedWriteBit Set if the file has shared write
permissions
5 fcbFileLockedBit Set if the file is locked (write-protected)
6 fcbOwnClumpBit Set if the file’s clump size is specified in
the FCB
7 fcbModifiedBit Set if the file has changed since it was last
flushed
fcbSBlk Used internally for volumes owned by the Macintosh file system. Your foreign file system can use this field for its own purposes.
fcbEOF Set to the logical end-of-file of the file.
fcbPLen Set to the physical end-of-file of the file.
fcbCrPs Set to the position of the mark.
fcbVPtr Set to point to the volume control block of the volume containing the file.
fcbBfAdr Reserved for internal use by the file system.
fcbFlPos Used internally for volumes owned by the Macintosh file system. Your foreign file system can use this field for its own purposes.
fcbClmpSize Set to the clump size of the file.
fcbBTCBPtr Reserved for internal use by the file system.
fcbExtRec For HFS volumes, this is an extent record (12 bytes) containing the first three extents of the file. Your foreign file system can use this field for its own purposes.
fcbFType Set to the file’s Finder type.
fcbCatPos For HFS volumes, a catalog hint, used when the file is closed. Your foreign file system can use this field for its own purposes.
fcbDirID The file’s parent directory ID number.
fcbCName The file’s name. This field consists of a length byte followed by 31 bytes. The file name must conform to the rules for HFS file names (i.e., no colon characters). For file systems that have no file-naming conventions, some standard name (such as “Untitled”) must be provided.
There are also four File System Utility routines that let you search the FCB array
• UTLocateFCB lets you find a FCB on a particular volume by file number or by file name
• UTLocateNextFCB resumes searching for a FCB by file number or file name from the FCB found by UTLocateFCB (the same file can have multiple access paths)
• UTIndexFCB lets you find, one at a time, all of the FCBs on a particular volume
• UTResolveFCB returns a pointer to a FCBRec given a file reference number
Note: If your foreign file system attempts to allocate a FCB in response to an _Open call and UTAllocateFCB cannot find a free FCB in the FCB array, you should return the tmfoErr result from UTAllocateFCB as your result. The Macintosh file system will then attempt to enlarge the FCB array and if successful, will retry the _Open call. Because enlarging the FCB array will change the array’s location in memory, you should never save the location of a FCBRec between calls to your foreign file system. A FCBRecPtr can only be used within the context of one file system operation.
Working Directory Control Blocks
Working directories allow applications that use the old MFS File Manager routines to work on volumes with directory trees. Working directories allow the use of a volume reference number to specify both a volume and a directory on the volume. Each time a working directory is opened on a volume owned by a foreign file system, the foreign file system must build a working directory control block (WDCB) in the WDCB array with the UTAllocateWDCB function.
When a working directory is closed, the foreign file system must mark the WDCB free and release it with the UTReleaseWDCB function. When a volume is unmounted and its VCB is disposed of, UTDisposeVCB closes all working directories open on the volume.
The structure of a working directory control block is defined by the WDCBRec data type.
struct WDCBRec {
VCBPtr wdVCBPtr; /* Pointer to VCB of this
working directory */
long wdDirID; /* Directory ID number of this
working directory */
long wdCatHint; /* Hint for finding this
working directory */
long wdProcID; /* Process that created this
working directory */
};
typedef struct WDCBRec WDCBRec;
typedef WDCBRec *WDCBRecPtr;
Field descriptions
wdVCBPtr A pointer to the VCB of the volume this working directory refers to.
wdDirID The directory ID number of the directory this working directory refers to.
wdCatHint The Macintosh file system stores a hint so it can quickly find the directory the working directory refers to. Your foreign file system can use this field for its own purposes.
wdProcID The process ID number passed to the OpenWD request.
The File System Utility routine UTResolveWDCB lets you search the WDCB array. UTResolveWDCB lets you find a WDCB by working directory reference number, or lets you find, one at a time, all WDCBs or all of the WDCBs with a particular process ID.
Note: If your foreign file system attempts to allocate a WDCB in response to an _OpenWD call and UTAllocateWDCB cannot find a free WDCB in the WDCB array, you should return the tmfoErr result from UTAllocateWDCB as your result. The Macintosh file system will then attempt to enlarge the WDCB array and if successful, will retry the _OpenWD call. Because enlarging the WDCB array will change the array’s location in memory, you should never save the location of WDCBRecs between calls to your foreign file system. A WDCBRecPtr can only be used within the context of one file system operation.
Drive Queue Elements
The File Manager maintains a list of all disk drives connected to the computer. It maintains this list in the drive queue, which is a standard Operating System queue. The drive queue is initially created at system startup time. Elements are added to the queue at system startup time or when the AddDrive function is called. The drive queue can support any number of drives, limited only by memory space. Each element in the drive queue contains information about the corresponding drive; the structure of a drive queue element is defined by the DrvQEl data type.
Given a drive number, the UTFindDrive File System Utility routine will return a pointer to the associated drive queue element if it is found in the drive queue.
struct DrvQEl {
QElemPtr qLink; /* Next queue entry */
short qType; /* Flag for dQDrvSz and
dQDrvSz2 */
short dQDrive; /* Drive number */
short dQRefNum; /* Driver reference number */
short dQFSID; /* File system ID */
unsigned short dQDrvSz; /* Number of logical blocks on
drive */
unsigned short dQDrvSz2; /* Additional field for large
drives */
};
typedef struct DrvQEl DrvQEl;
typedef DrvQEl *DrvQElPtr;
Field descriptions
qLink A pointer to the next entry in the drive queue. This field is initialized when the drive is added to the drive queue by _AddDrive.
qType The queue type. Used to specify the size of the drive. If the value of qType is 0, the number of logical blocks on the drive is contained in the dQDrvSz field alone. If the value of qType is 1, both dQDrvSz and dQDrvSz2 are used to store the number of blocks; in that case, dQDrvSz2 contains the high-order word of this number and dQDrvSz contains the low-order word.
dQDrive The drive number of the drive. This field is initialized when the drive is added to the drive queue by _AddDrive.
dQRefNum The driver reference number of the driver controlling the device on which the volume is mounted. This field is initialized when the drive is added to the drive queue by _AddDrive.
dQFSID An identifier for the file system handling the volume in the drive; it is zero for volumes handled by the File Manager and nonzero for volumes handled by other file systems.
dQDrvSz The number of logical blocks on the drive.
dQDrvSz2 An additional field to handle large drives. This field is used only if the qType field contains 1 and then, contains the high-order word specifying the number of logical blocks on the drive.
s Warning: If the device driver whose reference number is dQRefNum supports the Return Format List _Status call (csCode = 6), the volSize field in the returned FormatListRec with the diCIFmtFlagsCurrentBit set should be used to determine the number of blocks instead of the dQDrvSz and dQDrvSz2 fields in the DrvQEl. Drivers that support Return Format List (for example, the .Sony driver) may not support the dQDrvSz and dQDrvSz2 fields or may use them for other purposes. s
There are also four flag bytes preceding each drive queue element. The four flag bytes must be allocated by the disk driver at the same time the drive queue element is allocated. These bytes contain the following information:
Byte Contents
0 Bit 7=1 if the volume on the drive is locked
1 0 if no disk in drive; 1 or 2 if disk in drive; 8 if nonejectable disk in drive;
$FC–$FF if disk was ejected within last 1.5 seconds; $48 if disk in drive is
nonejectable but driver wants a call
2 Used internally during system startup
3 Bit 7=0 if disk is single-sided
You can read these flags by subtracting 4 from the beginning of a drive queue element.
After successfully mounting a volume, a foreign file system should change the dqFSID field in the drive queue element to the foreign file system’s file system ID number. When the volume is unmounted and the VCB is disposed of with UTDisposeVCB, UTDisposeVCB will clear the dqFSID field in the drive queue element if the device is ejectable.
The dqFSID field in drive queue elements for the Macintosh floppy disk drives are always initially zero. Other disk drivers should initialize the dqFSID field to either the file system ID number of the file system that formatted the disk, or to fsmGenericFSID ($ffff) if the file system cannot be identified.
File System Location Information
A file system must be able to determine the file, directory, or volume using information passed to it in a parameter block. This section tells how to use File System Utility routines to make that determination. The section titled “HFS Specifications” in Inside Macintosh: Files lists the various ways files or directories can be specified.
About Volume Reference Numbers
Each volume is given a unique volume reference number when the volume is mounted and the volume’s VCB is added to the VCB queue by UTAddNewVCB. A volume reference number is only valid for a particular volume while that volume is mounted. If a volume is unmounted and then mounted again, a new volume reference number will be assigned to the volume.
About Directory ID Numbers
A foreign file system must be able to assign a directory ID number to all directories on a volume. Each directory ID must be unique and cannot be used as a file number for the same volume. For directories other than the root directory (which must be fsRtDirID), the directory ID must be fsUsrCNID (16) or greater.
While a volume is mounted, directory IDs must remain the same. Directory IDs must be kept the same while a volume is unmounted. Macintosh programs and the Alias Manager use directory IDs to locate directories on the volume between volume mounts.
About File Numbers
A foreign file system must be able to assign a file number to all files on a volume. A file number is never passed as a parameter to a file system routine. Each file number must be unique and cannot be used as a directory ID number for the same volume. File numbers for files opened by programs using File Manager requests must be fsUsrCNID (16) or greater. File numbers less than fsUsrCNID are reserved for the root directory ID and for files opened by file systems for their own internal use (for example, the catalog and extents overflow files used by the HFS file system). The File Manager’s UnmountVol code returns fBsyErr to the caller and will not call your foreign file system if there are open files on the specified volume with file numbers fsUsrCNID or greater. If your foreign file system open files with file numbers less than fsUsrCNID, your foreign file system is responsible for closing those files before unmounting a volume.
While a volume is mounted, file numbers must remain the same. File numbers should, if at all possible, be kept the same while a volume is unmounted.
A foreign file system will use a file number in the file control block (FCB) of an open file. The file number can be used to find a FCB, and is used to identify multiple access paths to the same file by the UTAdjustEOF and UTCheckPermission File System Utility routines.
About File ID References
File ID references are an optional file system feature that allow the Alias Manager and other programs to track files that have been moved or renamed within a volume. If a foreign file system supports file ID references on its volumes, the foreign file system must be able to assign a file ID reference to a file, and later return that file’s location and name given only the file ID reference number, even if the file has been moved or renamed.
File ID reference numbers must be kept the same while a volume is unmounted. Macintosh programs and the Alias Manager use file ID reference numbers to locate files on the volume between volume mounts.
Determining the Volume
Before a foreign file system is called, the Macintosh file system and the File System Manager have determined what volume is the target of the call and what file system owns that volume. The volume is identified by the volume control block parameter passed to foreign file system’s HFSCIProc. UTDetermineVol can also be used to determine what volume is the target of a call.
Two file system calls are exceptions: _MountVol and _VolumeMount. _MountVol and _VolumeMount both deal with unmounted volumes (or potentially unmounted volumes), so the volume control block parameter passed to foreign file system’s HFSCIProc is unused.
Determining the File or Directory Location
A file’s location can be given in a file system call by full pathname, or by partial pathname. A directory’s location can be given by full pathname, partial pathname, or directory ID. A foreign file system must determine the directory ID the pathname starts in before the pathname to a file or directory can be parsed. Listing 3-2, GetCurrentDir, shows how to use the contents of the call’s parameter block and File System Utility routines to determine the directory parsing should begin in. The dirID input parameter contains the directory ID from the parameter block if that field is valid for the request recieved. Not all requests include a directory ID specification. For example, the old file system calls like PBOpen do not include a directory ID specification. GetCurrentDir returns a pointer to the volume’s VCB in volCtrlBlockPtr, the directory where parsing should begin is returned in currentDirectory, and the method used to determine the volume is returned in status.
Listing 3-2. Determining where directory parsing should start
OSErr GetCurrentDir(ParmBlkPtr pb, long dirID, VCBPtr *volCtrlBlockPtr,
long *currentDirectory, short *status)
{
OSErr result;
short moreMatches;
short vRefNum;
WDCBRecPtr wdCtrlBlockPtr;
WDPBRec wdpb;
result = UTDetermineVol(pb, status, &moreMatches, &vRefNum,
volCtrlBlockPtr);
if (result == noErr)
{
switch (*status)
{
/* Determined by full pathname */
case dtmvFullPathame:
/* Current directory is always the root directory */
*currentDirectory = fsRtDirID;
break;
/* Determined by volume refNum or by drive number */
case dtmvVRefNum:
case dtmvDriveNum:
/* Current directory is dirID if specified; */
/* otherwise, it's the root directory */
if (dirID != 0)
*currentDirectory = dirID;
else
*currentDirectory = fsRtDirID;
break;
/* Determined by working directory refNum */
case dtmvWDRefNum:
/* Current directory is dirID if specified; */
/* otherwise, it's wdDirID in the WDCB */
if (dirID != 0)
*currentDirectory = dirID;
else
{
result = UTResolveWDCB(0, 0, pb->fileParam.ioVRefNum,
&wdCtrlBlockPtr);
if (result == noErr)
*currentDirectory = wdCtrlBlockPtr->wdDirID;
}
break;
/* Determined by default volume */
case dtmvDefault:
/* Current directory is dirID if specified; */
/* otherwise, it's the default directory */
if (dirID != 0)
*currentDirectory = dirID;
else
{
wdpb.ioNamePtr = NULL; /* the name not needed */
result = UTGetDefaultVol(&wdpb);
if (result == noErr)
*currentDirectory = wdpb.ioWDDirID;
}
break;
/* This should never happen, but... */
default:
result = paramErr;
break;
}
}
return (result);
}
Once the directory ID where parsing will begin has been determined, the pathname (if any) must be parsed to find the object. The process of parsing a pathname consists of getting the next component in a pathname and determining where that component is on the volume, and then repeating those two steps until the end of the pathname is reached. Parsing can go either up or down in a volume’s directory heirarchy so a foreign file system must be able to find an object by name within a specified directory to move down in the heirarchy and must be able to find an object’s parent directory to move up in the heirarchy. Listing 3-3 shows how to parse a pathname. How a foreign file system finds an object on a volume is specific to the foreign file system.
Listing 3-3. Parsing a pathname
struct ObjectInfoRec {
long parentDirID; /* the directory ID of the parent */
Str31 localName; /* the local name within said directory */
Boolean exists; /* TRUE if the object exists */
Boolean isDir; /* TRUE if the object is a directory */
long objectNumber; /* directory ID or file number of object */
};
typedef struct ObjectInfoRec ObjectInfoRec;
typedef ObjectInfoRec *ObjectInfoRecPtr;
OSErr ParsePathName (VCBPtr theVCB, long currentDirectory,
StringPtr namePtr, ObjectInfoRecPtr objectInfo)
{
OSErr result;
ParsePathRec parseRec;
Str31 lastComponent;
/* init parseRec to start parsing at beginning of namePtr */
parseRec.namePtr = namePtr;
parseRec.startOffset = 0;
parseRec.ComponentLength = 0;
parseRec.moreName = false;
parseRec.foundDelimiter = false;
/* Get the length of the volume name (if any) and use it to adjust
** the startOffset to point to the beginning of the partial pathname.
** UTParsePathname also ensures the pathname is not NULL or an empty
** string.
*/
result = UTParsePathname(&parseRec.startOffset, parseRec.namePtr);
if (result == noErr)
{
/* At this point, startOffset is pointing at the first
** character of a partial pathname (if any). For example:
** namePtr = 'VolName:a:b:c' (full pathname)
** startOffset = ^
** namePtr = ':a:b:c' (partial pathname)
** startOffset = ^
** namePtr = 'a' (partial pathname)
** startOffset = ^
** namePtr = 'VolName:' (full pathname)
** startOffset = ^
*/
/* Check for leading delimiter of the partial pathname */
result = UTGetPathComponentName(&parseRec);
if (result == noErr)
{
if (parseRec.ComponentLength == 0 && parseRec.foundDelimiter)
{
/* Get past initial delimiter */
++parseRec.startOffset;
}
/* At this point, startOffset is pointing at the first
** character of the first component name (if any).
** For example:
** namePtr = 'VolName:a:b:c' (full pathname)
** startOffset = ^ (moreName = true,
** componentLength = 0)
** namePtr = ':a:b:c' (partial pathname)
** startOffset = ^ (moreName = true,
** componentLength = 0)
** namePtr = 'a' (partial pathname)
** startOffset = ^ (moreName = true,
** componentLength = 0)
** namePtr = 'VolName:' (full pathname)
** startOffset = ^ (moreName = false,
** componentLength = 0)
*/
/* Parse until there is no more pathname to parse. */
while ((result == noErr) && parseRec.moreName)
{
/* Search for the next delimiter from startOffset. */
result = UTGetPathComponentName(&parseRec);
if (result == noErr)
{
if (parseRec.ComponentLength == 0)
{
/* A delimiter was found immediately following another
** delimiter. Set current directory to parent of
** current directory. If current directory is
** fsRtDirID, then return bdNamErr (that handles the
** case of 'Root::' or 'Root:SubDir:::', etc.)
*/
if (currentDirectory != fsRtDirID)
{
/* Call foreign file system specific code to get
** parent of current directory
*/
result = FFSGetParent(theVCB, currentDirectory,
¤tDirectory);
}
else
{
/* Pathname tried to go up from root directory */
result = bdNamErr;
}
/* startOffset = start of next component (if any). */
++parseRec.startOffset;
}
else if (parseRec.moreName)
{
/* A component was found and it isn't the last
** component, so it must be a directory. Make
** lastComponent in current directory the new current
** directory.
*/
lastComponent[0] = parseRec.ComponentLength;
BlockMove((Ptr)((long)parseRec.namePtr +
parseRec.startOffset + 1),
&lastComponent[1],
parseRec.ComponentLength);
/* Call foreign file system specific code to get
** directory by name in currentDirectory
*/
result = FFSGetDir(theVCB, lastComponent,
currentDirectory, ¤tDirectory);
/* startOffset = start of next component (if any). */
result = bdNamErr; /* Default to bad name (if ioNamePtr != NULL
** or ioNamePtr doesn't point to an empty
** string). Otherwise, the code that follows
** will set up the real result.
*/
if ((namePtr == NULL) || (namePtr[0] == 0))
{
/* pathname was NULL or a zero length string, so we found a
** directory at the end of the string
*/
objectInfo->isDir = true;
objectInfo->objectNumber = currentDirectory;
/* Call foreign file system specific code to get information on
** this directory
*/
result = FFSGetDirInfo(theVCB, objectInfo);
}
}
return (result);
}
The Macintosh Volume Cache
The Macintosh operating system uses a volume (disk) cache for input and output operations. The following sections provide both general information about caching and specific information about the volume cache used by the Macintosh operating system.
About the Macintosh Volume Cache
The Macintosh operating system allows users to set aside memory for a general-purpose volume cache. A volume cache is an area in memory that is used to store blocks that have been recently read from or written to a volume. By keeping blocks in memory that are likely to be read or written again, a file system can avoid repeating I/O operations to the volume’s device and, as a result, can save a great deal of time. Use of the cache can greatly increase the speed of many applications. The one disadvantage is that memory set aside for the cache is unavailable to applications.
How Users Control the Cache
The Memory control panel allows users to change the amount of memory set aside for the cache. The Memory control panel allows users to reclaim some, but not all, of the memory used by the cache when necessary.
Although a foreign file system cannot determine the size of the cache, there is always at least 32K set aside for the cache.
The Cache and Foreign File Systems
A foreign file system can gain access to the cache by using the cache routines provided by the File System Manager. Foreign file system’s should try to use these routines for all input/output operations. There are a number of reasons why a foreign file system should use the cache routines instead of calling a device driver directly:
• Increased throughput: By reducing the number of input/output operations, use of the cache can dramatically increase throughput.
• Users can control the cache: The Control Panel lets users control the amount of memory set aside for caching.
• Easier implementation: The foreign file system does not have to allocate a buffer for an entire block when only part of a block is to be transferred.
• Support for both logical and physical blocks: The Macintosh cache routines can perform operations involving physical blocks on a volume or logical blocks for a file.
• Asynchronous execution: All cache routines that transfer data to or from a volume execute asynchronously. This means that control can be returned from the Macintosh file system to the caller before an input or output operation is complete. (Although to the foreign file system it appears that the cache routine waits until the operation has completed, the Macintosh file system returns control to the caller—unless the original trap was requested to be run synchronously—while waiting for the I/O operation to finish. When the I/O operation is complete, the Macintosh file system returns control to the foreign file system in such a way that normal completion of the foreign file system routine will allow execution of the application’s code to resume where it was interrupted.)
s Warning: It is important to note the use of the cache routines is the only way a foreign file system can perform asynchronous I/O. If a foreign file system calls a device driver directly, all I/O operations are executed synchronously, even if the calling application has requested asynchronous I/O. If your foreign file system is called at interrupt time and the device driver (or another device driver called by the device driver) is busy, calling the device driver directly will deadlock the Macintosh system. For this reason, all calls to most device drivers should be made through the cache routines. s
Cache Blocks
Each cache block is made up of header information that identifies the volume and file (if any) from which the data was taken and an offset that identifies how far, in bytes, the block was from the beginning of the volume (for volume I/O) or the beginning of the file (for file I/O) and 512 bytes of data. The structure of cache block headers and where they reside in memory is undefined. Cache routines that work with individual cache blocks always use a pointer to the cache block’s data.
The Macintosh volume cache has four categories of cache blocks:
• Reserved cache blocks - A cache block that is in use is reserved. A reserved cache block corresponds to a logical block of a file or a physical block of a volume and is not available for reuse. A cache block is reserved with the UTGetBlock function. A reserved cache block can contain clean or dirty data (or no valid data at all if the cache block was obtained for use as a write buffer). Cache blocks should not be reserved between calls to a file system.
• Released cache blocks - A cache block that is very likley to be needed again but is not reserved should be released. A released cache block still corresponds to a block of the file or volume, but is available for reuse. A released cache block can contain clean or dirty data.
• Free cache blocks - A cache block that isn’t likley to be used again should be marked free. A free cache block still contains valid data and is still associated with the corresponding block of the volume, but not with a file on the volume. Dirty cache blocks should be flushed before marking them free. Free cache blocks will be reused before released cache blocks.
• Trashed cache blocks - A cache block that will never be used again should be trashed. Trashing a cache block marks the cache block empty. Dirty cache blocks should be flushed before trashing them. Trashed cache blocks will be reused before released or free cache blocks.
As mentioned above, a cache block can be dirty or clean. A cache block is dirty when its contents do not match the contents of the corresponding block on the volume. To update the volume, a dirty cache block must be flushed by writing its contents out to the volume. This occurs in the following cases:
• The Macintosh operating system replaces a released cache block that is dirty with a block from the volume that is being read into the cache. When this occurs, the dirty cache block is flushed before it is replaced.
• The foreign file system flushes the dirty cache block in response to a _FlushFile, _Close, or _FlushVol call.
• The foreign file system flushes a cache block at some other time (for example, when handling a _Write call).
When using the cache routines, remember that any cache operation may force a previously cached block to be removed from memory. If there are no trashed or free cache blocks, a new block that is read into the cache from the volume replaces the contents of the least recently used of the released blocks (if any) in the cache.
Logical to Physical Block Mapping
The Macintosh cache routines can read or write either logical blocks of a file or physical blocks of a volume. However, because disk driver device calls always read or write physical blocks of a volume, a foreign file system must provide a routine to map logical file blocks to physical volume blocks called the logical to physical routine. The address of the logical to physical routine is passed to the File System Manager in the foreign file system’s HFSCIRec and as a parameter to some cache routines. The interface for the logical to physical routine a FSM-based foreign file system must supply is defined in “The HFS Component Interface” chapter.
It is the responsibility of the foreign file system to return an eofErr when a request for data is beyond the current logical end of file. It is the responsibility of the logical to physical routine to return an eofErr error when a cache routine asks for block mapping beyond the current physical end of file.
File System Utility Routines
UTAllocateFCB
Use the UTAllocateFCB function to allocate a FCBRec in the FCB array when opening a file.
pascal OSErr UTAllocateFCB(short *fileRefNum,
FCBRecPtr *fileCtrlBlockPtr);
fileRefNum Contains a pointer to a short. UTAllocateFCB places the file reference number of the allocated FCBRec into the field referred to by this parameter.
fileCtrlBlockPtr Contains a pointer to a FCBRecPtr. UTAllocateFCB places a pointer to the allocated FCBRec into the field referred to by this parameter.
If an FCBRec can be allocated in the FCB array, the FCB will be marked in use (fcbFlNm is set to -1), the file reference number will be returned in fileRefNum, and a pointer to the allocated FCBRec will be returned in fileCtrlBlockPtr. The allocated FCBRec is not initialized in any way. It is up to your foreign file system to initialize all fields in the FCBRec.
If an FCB cannot be allocated because there are no FCBRecs left in the FCB array, this function will return a tmfoErr.
Note: If your foreign file system returns the tmfoErr result from UTAllocateFCB as the result to _Open, the Macintosh file system will attempt to enlarge the FCB array and if successful, will retry the _Open call. Because enlarging the FCB array will change the array’s location in memory, you should never save the location of a FCBRec between calls to your foreign file system. A FCBRecPtr can only be used within the context of one file system operation.
When you no longer need an allocated FCBRec (either because the file could not be opened or when the file is closed), release it with UTReleaseFCB.
Result codes
noErr 0 No error
tmfoErr -42 There are no free FCBRecs in the FCB array
UTReleaseFCB
Use the UTReleaseFCB function to release an allocated FCBRec in the FCB array when closing a file.
pascal OSErr UTReleaseFCB(short fileRefNum);
fileRefNum Contains the file reference number that specifies the FCBRec to release.
When you no longer need an allocated FCBRec (either because the file could not be opened or when the file is closed), release it with UTReleaseFCB. UTReleaseFCB will release an FCBRec in the FCB array and mark it free (the FCBRec is cleared).
Result codes
noErr 0 No error
fnOpnErr -38 The file is not open
rfNumErr -51 The file reference number is not valid
UTLocateFCB
Use the UTLocateFCB function to find a FCBRec in the FCB array.
pascal OSErr UTLocateFCB(VCBPtr volCtrlBlockPtr, unsigned long fileNum,
StringPtr namePtr, short *fileRefNum,
FCBRecPtr *fileCtrlBlockPtr);
volCtrlBlockPtr Contains a VCBPtr that specifies the volume the open file is on.
fileNum Contains a file number that specifies the FCBRec to search for. If you want to find the FCBRec by file name, set this parameter to zero.
namePtr Contains a pointer to a string that specifies the file name to search for. This parameter is ignored if fileNum is not zero.
fileRefNum Contains a pointer to a short. UTLocateFCB places the file reference number of the FCBRec found into the field referred to by this parameter.
fileCtrlBlockPtr Contains a pointer to a FCBRecPtr. UTLocateFCB places a pointer to the FCBRec found into the field referred to by this parameter.
UTLocateFCB will find a FCBRec in the FCB array that’s on the volume specified by volCtrlBlockPtr. If fileNum is not zero, UTLocateFCB will search the FCB array for the first FCBRec that has a matching file number. If fileNum is zero, UTLocateFCB will search the FCB array for the first FCBRec that has a matching file name. UTLocateFCB always starts searching from the beginning of the FCB array and returns the first match it finds. UTLocateFCB returns the file reference number of the matching FCBRec in fileRefNum and a pointer to the matching FCBRec in fileCtrlBlockPtr.
Result codes
noErr 0 No error
fnfErr -38 A matching FCB was not found
UTLocateNextFCB
Use the UTLocateNextFCB function to continue seaching for a FCBRec in the FCB array.
volCtrlBlockPtr Contains a VCBPtr that specifies the volume the open file is on.
fileNum Contains a file number that specifies the FCBRec to search for. If you want to find the FCBRec by file name, set this parameter to zero.
namePtr Contains a pointer to a string that specifies the file name to search for. This parameter is ignored if fileNum is not zero.
fileRefNum Contains a pointer to a short. On input, the field referred to by this parameter contains the file reference number of the last match found by UTLocateFCB or UTLocateNextFCB. On output, UTLocateNextFCB places the file reference number of the FCBRec found into the field referred to by this parameter.
fileCtrlBlockPtr Contains a pointer to a FCBRecPtr. UTLocateFCB places a pointer to the FCBRec found into the field referred to by this parameter.
UTLocateNextFCB will find a FCBRec in the FCB array that’s on the volume specified by volCtrlBlockPtr. If fileNum is not zero, UTLocateNextFCB will search the FCB array for a FCBRec that has a matching file number. If fileNum is zero, UTLocateNextFCB will search the FCB array for a FCBRec that has a matching file name. UTLocateNextFCB always starts searching from the FCBRec specified by fileRefNum and returns the next match it finds. UTLocateNextFCB returns the file reference number of the matching FCBRec in fileRefNum and a pointer to the matching FCBRec in fileCtrlBlockPtr.
Result codes
noErr 0 No error
fnfErr -38 A matching FCB was not found
UTIndexFCB
Use the UTIndexFCB function to index through the open FCBs on a volume.
pascal OSErr UTIndexFCB(VCBPtr volCtrlBlockPtr, short *fileRefNum,
FCBRecPtr *fileCtrlBlockPtr);
volCtrlBlockPtr Contains a VCBPtr that specifies the volume the open file is on.
fileRefNum Contains a pointer to a short. On input, the field referred to by this parameter contains the file reference number of the last match found by UTIndexFCB or zero to search for the first FCBRec. On output, UTIndexFCB places the file reference number of the FCBRec found into the field referred to by this parameter.
fileCtrlBlockPtr Contains a pointer to a FCBRecPtr. UTIndexFCB places a pointer to the FCBRec found into the field referred to by this parameter.
UTIndexFCB will find a FCBRec in the FCB array that’s on the volume specified by volCtrlBlockPtr. UTIndexFCB always starts searching from the FCBRec specified by fileRefNum and returns the next FCBRec it finds on the specified volume. UTIndexFCB returns the file reference number of the matching FCBRec in fileRefNum and a pointer to the matching FCBRec in fileCtrlBlockPtr.
Result codes
noErr 0 No error
fnfErr -38 A matching FCB was not found
rfNumErr -51 The file reference number is not valid
UTResolveFCB
Use the UTResolveFCB function to map a file reference number to its FCBRec.
pascal OSErr UTResolveFCB(short fileRefNum,
FCBRecPtr *fileCtrlBlockPtr);
fileRefNum Contains a file reference number that specifies the FCBRec.
fileCtrlBlockPtr Contains a pointer to a FCBRecPtr. UTResolveFCB places a pointer to the FCBRec found into the field referred to by this parameter.
Given a file reference number, UTResolveFCB returns a pointer to a FCBRec in fileCtrlBlockPtr.
If the file reference number is valid, UTResolveFCB will return noErr; even if the file is not open. You can use UTCheckFileRefNum to see if a file reference number refers to an open file.
Result codes
noErr 0 No error
rfNumErr -51 The file reference number is not valid
UTAllocateVCB
Use the UTAllocateVCB function to allocate memory in the system heap for a new VCB.
pascal OSErr UTAllocateVCB(unsigned short *sysVCBLength,
VCBPtr *volCtrlBlockPtr,
unsigned short addSize);
sysVCBLength Contains a pointer to an unsigned short. UTAllocateVCB places the size of the system VCB into the field referred to by this parameter.
volCtrlBlockPtr Contains a pointer to an VCBPtr. UTAllocateVCB places a pointer to the new VCB into the field referred to by this parameter.
addSize Contains the amount of addition storage to allocate for the foreign file system’s private use, or zero.
UTAllocateVCB will allocate cleared memory from the system heap for a new VCB. The amount of memory allocated by UTAllocateVCB is determined by adding the size of the system VCB structure to the amount of additional memory needed for the foreign file system’s private use. A pointer to the new VCB is returned in volCtrlBlockPtr and the size of the system VCB structure is returned in sysVCBLength. Thus, the additional foreign file system private data (if any) starts at volCtrlBlockPtr + sysVCBLength.
Result codes
noErr 0 No error
memFullErr -108 The VCB could not be allocated; no memory
available
UTAddNewVCB
Use the UTAddNewVCB function to add a new VCB to the VCB queue and assign a volume reference number to the volume.
pascal OSErr UTAddNewVCB(short driveNum, short *vRefNum,
VCBPtr volCtrlBlockPtr);
driveNum Contains the drive number of the drive the volume is on.
vRefNum Contains a pointer to a short. UTAddNewVCB places the volume reference number assigned to the volume into the field referred to by this parameter.
volCtrlBlockPtr Contains a pointer to the VCB to add to the VCB queue.
UTAddNewVCB assigns an unused volume reference number to a VCB and adds it to the VCB queue. The volume reference number is returned in vRefNum.
The following fields in the VCB are also initialized by UTAddNewVCB
• qType is assigned fsQType (5).
• vcbDrvNum is assigned the drive number of the drive the volume is on
• vcbDRefNum is assigned the driver reference number of the drive the volume is on
• vcbVRefNum is assigned the volume reference number
• vcbBufAdr may be assigned a value for the system’s cache use.
If the VCB is the first VCB added to the VCB queue (this will probably never happen for a foreign file system), UTAddNewVCB will also make the volume the default volume.
Result codes
noErr 0 No error
paramErr -50 volCtrlBlockPtr was NULL
nsDrvErr -56 The drive specified by driveNum could not be
found in the drive queue
UTDisposeVCB
Use the UTDisposeVCB function to dispose of a VCB allocated with the UTAllocateVCB function.
volCtrlBlockPtr Contains a pointer to the VCB to dispose.
UTDisposeVCB performs the following
• Close all working directories on the volume
• Remove the VCB from the VCB queue
• If the volume’s drive is ejectable, clear the dQFSID field in the DrvQEl of the volume’s drive (a disk owned by another file system could be the next disk inserted into the ejectable drive)
• If the volume is the default volume, clear the system’s default volume
• Dispose of the memory used by the VCB
You should always use UTDisposeVCB to dispose of your VCB instead of freeing the memory yourself.
Result codes
noErr 0 No error
nsDrvErr -56 The volume’s drive could not be found in the
drive queue
UTLocateVCBByRefNum
Use the UTLocateVCBByRefNum function to locate a VCB using a volume reference number, drive number, or working.directory number.
pascal OSErr UTLocateVCBByRefNum(short refNum, short *vRefNum,
VCBPtr *volCtrlBlockPtr);
refNum Contains a volume reference number, drive number, or working directory number.
vRefNum Contains a pointer to a short. UTLocateVCBByRefNum places the reference number of the volume found into the field referred to by this parameter.
volCtrlBlockPtr Contains a pointer to a VCBPtr. UTLocateVCBByRefNum places a pointer to the VCB found into the field referred to by this parameter.
UTLocateVCBByRefNum finds the VCB associated with a volume reference number, drive number, or working.directory number and returns a pointer to the VCB in volCtrlBlockPtr and the volume reference number in vRefNum.
Result codes
noErr 0 No error
rfNumErr -51 The working directory reference number is
invalid
nsvErr -56 A matching volume could not be found in the
VCB queue
UTLocateVCBByName
Use the UTLocateVCBByName function to locate the first VCB that matches the volume name specified.
pascal OSErr UTLocateVCBByName(StringPtr namePtr, short *moreMatches,
short *vRefNum, VCBPtr *volCtrlBlockPtr)
namePtr Contains a pointer to a volume name (which must end with a colon ‘:’ character) or to a full pathname.
moreMatches Contains a pointer to a short. If there is another volume with a matching name, UTLocateVCBByName places the length of the volume name (not including the trailing colon) into the field referred to by this parameter. If this is the last volume with a matching name or no matches are found, UTLocateVCBByName places zero into the field referred to by this parameter.
vRefNum Contains a pointer to a short. UTLocateVCBByName places the reference number of the volume found into the field referred to by this parameter.
volCtrlBlockPtr Contains a pointer to a VCBPtr. UTLocateVCBByName places a pointer to the VCB found into the field referred to by this parameter.
UTLocateVCBByName finds the first VCB with the specified volume name and returns a pointer to the VCB in volCtrlBlockPtr and the volume reference number in vRefNum.
UTLocateVCBByName also checks to see if there are more volumes in the VCB queue with the specified name. If there are, moreMatches returns the length of the volume name. If the volume found is the only volume with the specified name (or if no matching volumes are found), moreMatches returns zero. To find the next volume with a matching name, use the UTLocateNextVCB routine.
Result codes
noErr 0 No error
bdNamErr -37 namePtr was NULL, or namePtr does not point
to a volume name or full pathname
nsvErr -56 A matching volume could not be found in the
VCB queue
UTLocateNextVCB
Use the UTLocateNextVCB function to continue seaching for a VCB by name in the VCB queue.
pascal OSErr UTLocateNextVCB(StringPtr namePtr, short *moreMatches,
short *vRefNum, VCBPtr *volCtrlBlockPtr);
namePtr Contains a pointer to a volume name (which must end with a colon ‘:’ character) or to a full pathname.
moreMatches Contains a pointer to a short. On input, the field referred to by this parameter contains the length of the volume name as returned by a previous call to UTLocateVCBByName or UTLocateNextVCB, or zero to force UTLocateNextVCB to re-parse the pathname. On output, UTLocateNextVCB places the length of the volume name (not including the trailing colon) into the field referred to by this parameter. If this is the last volume with a matching name or no matches are found UTLocateNextVCB places zero into the field referred to by this parameter.
vRefNum Contains a pointer to a short. UTLocateNextVCB places the reference number of the volume found into the field referred to by this parameter.
volCtrlBlockPtr Contains a pointer to a VCBPtr. UTLocateNextVCB places a pointer to the VCB found into the field referred to by this parameter.
UTLocateNextVCB finds the next VCB with the specified volume name. UTLocateNextVCB always starts searching from the VCB specified by volCtrlBlockPtr and returns the next VCB it finds in the VCB queue. UTLocateNextVCB returns a pointer to the VCB in volCtrlBlockPtr and the volume reference number in vRefNum.
After finding a match, UTLocateNextVCB also checks to see if there are more volumes in the VCB queue with the specified name. If there are, moreMatches returns the length of the volume name. If the volume found is the only volume with the specified name (or if no matching volumes are found), moreMatches returns zero.
Result codes
noErr 0 No error
bdNamErr -37 namePtr was NULL, or namePtr does not point
to a volume name or full pathname
nsvErr -56 A matching volume could not be found in the
VCB queue
UTAllocateWDCB
Use the UTAllocateWDCB function to allocate a working directory in the WDCB array.
pascal OSErr UTAllocateWDCB(WDPBPtr paramBlock);
paramBlock Contains a pointer to a working directory parameter block.
Parameter Block
´ ioVRefNum short On input, contains the volume reference
number. On output, contains the
working directory reference number.
¨ ioWDCreated short If a working directory is not created,
zero is returned. If a working directory
is created, non-zero is returned.
Æ ioWDProcID long Contains the working directory user
identifier.
Æ ioWDDirID long Contains the working directory’s
directory ID.
UTAllocateWDCB uses the ioVRefNum, ioWDProcID, and ioPDDirID fields in the WDPBRec to allocate a working directory in the WDCB array. UTAllocateWDCB places the working directory reference number into the ioVRefNum field of the WDPBRec.
If the specified directory has already been made a working directory using the same ioWDProcID value, a new working directory will not be allocated; instead, the existing working directory reference number will be returned and ioWDCreated will be set to zero.
Note: The ioWDCreated field is named filler1 in current versions of Files.C.
If a WDCB array cannot be allocated, this function will return a tmfoErr.
Note: If all WDCBRecs in the WDCB array are in use, an attempt will be made to enlarge the WDCB array. Because enlarging the WDCB array will change the array’s location in memory, you should never save the location of a WDCBRec between calls to your foreign file system. A WDCBRecPtr can only be used within the context of one file system operation.
When you no longer need an allocated working directory, release it with UTReleaseWDCB.
Result codes
noErr 0 No error
tmfoErr -42 There are no free WDCBRecs in the WDCB
array
UTReleaseWDCB
Use the UTReleaseWDCB function to release an allocated working directory in the WDCB array when closing a working directory.
pascal OSErr UTReleaseWDCB(short wdRefNum);
wdRefNum Contains the working directory reference number that specifies the working directory to release.
When you no longer need an allocated working directory, release it with UTReleaseWDCB. UTReleaseWDCB will release an WDCBRec in the WDCB array and mark it free.
Result codes
noErr 0 No error
rfNumErr -51 The working directory reference number is not
valid or does not refer to an open working
directory
UTResolveWDCB
Use the UTResolveWDCB function to find a WDCBRec in the WDCB array.
pascal OSErr UTResolveWDCB(long procID, short wdIndex, short wdRefNum,
WDCBRecPtr *wdCtrlBlockPtr);
procID Contains a working directory user identifier or zero
wdIndex Contains an index.
wdRefNum Contains the working directory reference number that specifies the working directory, or contains a volume reference number or drive number that specifies the volume.
wdCtrlBlockPtr Contains a pointer to a WDCBRecPtr. UTResolveWDCB places a pointer to the WDCBRec found into the field referred to by this parameter.
UTResolveWDCB locates a WDCBRec in the WDCB array according to these rules:
• If wdIndex is zero or negative, UTResolveWDCB uses the working directory reference number in wdRefNum to find the WDCBRec. The procID parameter is ignored in this case.
• If wdIndex is positive and procID is zero, UTResolveWDCB finds the WDCBRec whose working directory index is wdIndex on the volume specified by wdRefNum.
• If wdIndex is positive and procID is non-zero, UTResolveWDCB finds the WDCBRec whose working directory index is wdIndex with the working directory user identifier specified by procID on the volume specified by wdRefNum.
Result codes
noErr 0 No error
nsvErr -35 No matching working directory was found by
the indexed search
rfNumErr -51 The working directory reference number is not
valid or does not refer to an open working
directory
UTFindDrive
Use the UTFindDrive function to find a drive queue element in the drive queue.
driveNum Contains the drive number that specifies the drive.
driveQElementPtr Contains a pointer to a DrvQElPtr. UTFindDrive places a pointer to the drive queue element found into the field referred to by this parameter.
UTFindDrive locates a drive queue element in the drive queue. If a matching drive queue element is found and its dQFSID field is zero, UTFindDrive will return noErr. If a matching drive queue element is found and its dQFSID field is not zero (when the drive is owned by a foreign file system), UTFindDrive will return extFSErr.
Result codes
noErr 0 A matching drive queue element was found
with a zero dQFSID field
nsDrvErr -56 No matching drive queue element was found
extFSErr -58 A matching drive queue element was found
with a non-zero dQFSID field
UTAdjustEOF
Use the UTAdjustEOF function to adjust the logical and physical EOF of all open FCBs for the specified file fork.
pascal OSErr UTAdjustEOF(short fileRefNum);
fileRefNum Contains a file reference number that specifies the reference FCBRec.
UTAdjustEOF finds the open FCB specified by fileRefNum and gets that file’s file number and VCBPtr. UTAdjustEOF then copies the logical end of file (fcbEOF) and physical end of file (fcbPLen) from the specified FCBRec to all other open FCBRecs that refer to the same file fork.
Result codes
noErr 0 No error
rfNumErr -51 The file reference number is not valid
UTSetDefaultVol
Use UTSetDefaultVol to set the default volume and working directory in response to _SetVol or _HSetVol.
pascal OSErr UTSetDefaultVol(long nodeHint, unsigned long dirID,
short refNum);
nodeHint Contains a long that specifies optional file system specific information about the directory.
dirID Contains a directory ID or 0.
refNum Contains a volume reference number or a working directory number.
The parameters you pass to UTSetDefaultVol depend on which file system call you are responding to, _SetVol or _HSetVol, and on the parameters passed the file system call.
If you are responding to _SetVol and ioVRefNum is a working directory number, then refNum must be set to the working directory number (ioVRefNum), dirID must be 0, and nodeHint is ignored (nodeHint information is obtained from the working directory specified).
If you are responding to _SetVol and ioVRefNum is a volume reference number or drive number, then refNum must be the volume reference number (obtained from vcbVRefNum in the VCB), dirID must be set to fsRtDirID, and nodeHint can contain optional file system specific information about the directory that you supply.
If you are responding to _HSetVol, then refNum must be the volume reference number (obtained from vcbVRefNum in the VCB), dirID must be be the directory specified by the combination of ioVRefNum, ioDirID and ioNamePtr, and nodeHint can contain optional file system specific information about the directory that you supply.
Result codes
noErr 0 No error
rfNumErr -51 The refNum is invalid
UTGetDefaultVol
Use UTGetDefaultVol to get the default volume and working directory in response to _GetVol or _HGetVol.
pascal OSErr UTGetDefaultVol(WDPBPtr paramBlock);
paramBlock Contains a pointer to a working directory parameter block.
Parameter Block
¨ ioNamePtr long Contains a pointer to a Str31 or
NULL. If not NULL, UTGetDefaultVol
will return the volume’s name in the Str31
specified by this field.
¨ ioVRefNum short UTGetDefaultVol places the working
directory number of the default volume
in this field.
¨ ioWDProcID long UTGetDefaultVol places the working
directory user identifier in this field.
¨ ioWDVRefNum short UTGetDefaultVol places the volume
reference number of the default volume
in this field.
¨ ioWDDirID long UTGetDefaultVol places the directory
ID number of the default directory in
this field.
UTGetDefaultVol returns the default volume name, the default volume’s working directory number, the default volume’s user identifier, the default volume’s volume reference number, and the default directory’s directory ID number.
Result codes
noErr 0 No error
nsvErr -35 The default directory is not set
UTEjectVol
Use UTEjectVol to eject a volume and mark it offline.
pascal OSErr UTEjectVol(VCBPtr volCtrlBlockPtr);
volCtrlBlockPtr Contains a pointer to the VCB of the volume to eject and mark offline.
UTEjectVol ejects and marks offline the volume specified by volCtrlBlockPtr. If the volume has already been ejected, UTEjectVol does nothing and returns noErr. If the volume is already offline, but has not been ejected, UTEjectVol will eject it.
If the volume’s drive is ejectable, UTEjectVol clears the dQFSID field in the DrvQEl of the volume’s drive (a disk owned by another file system could be the next disk inserted into the ejectable drive).
Note: Before calling UTEjectVol, the foreign file system must flush any cached data associated with the volume using UTFlushCache. If the device is ejectable, UTFlushCache's fcOption should be set to fcTrashMask. If the device is not ejectable, UTFlushCache's rbOption should be set to rbDefault.
Result codes
noErr 0 No error
paramErr -50 volCtrlBlockPtr does not point to a valid VCB
any of the result codes returned by the disk driver to an eject call
UTCheckWDRefNum
Use UTCheckWDRefNum to make sure a working directory reference number is valid and open.
pascal OSErr UTCheckWDRefNum(short wdRefNum);
wdRefNum Contains the working directory reference number.
UTCheckWDRefNum will return noErr if a working directory reference number is valid and open.
Result codes
noErr 0 No error
rfNumErr -51 The working directory reference number is not
valid or does not refer to an open working
directory
UTCheckFileRefNum
Use UTCheckFileRefNum to make sure a file reference number is valid and open.
pascal OSErr UTCheckFileRefNum(short fileRefNum);
fileRefNum Contains the file reference number.
UTCheckFileRefNum will return noErr if a file reference number is valid and open.
Result codes
noErr 0 No error
rfNumErr -51 The file reference number is not valid or does
not refer to an open file
UTCheckVolRefNum
Use UTCheckVolRefNum to make sure a volume reference number is valid.
pascal OSErr UTCheckVolRefNum(short vRefNum);
vRefNum Contains the volume reference number.
UTCheckVolRefNum will return noErr if a volume reference number is valid. The vRefNum parameter must be a volume reference number, not a driver number, zero, or a working directory reference number.
Result codes
noErr 0 No error
rfNumErr -51 The volume reference number is not valid
UTCheckPermission
Use UTCheckPermission to check the file access permission requested in response to _Open or _OpenRF if your foreign file system is using the Macintosh file system’s access permission model.
pascal OSErr UTCheckPermission(VCBPtr volCtrlBlockPtr, short *modByte,
unsigned long fileNum,
ParmBlkPtr paramBlock);
volCtrlBlockPtr Contains a VCBPtr that specifies the volume the file to be opened is on.
modByte Contains a pointer to a short. On input, the field referred to by this parameter contains the values your file system plans to put into the fcbFlags (in the high byte) and fcbTypByt (in the low byte) fields in the FCB. On output, UTCheckPermission places the corrected values for fcbFlags and fcbTypByt into the field referred to by this parameter.
fileNum Contains a file number that specifies the file to be opened.
paramBlock Contains a pointer to the parameter block used to make the _Open or _Open request.
UTCheckPermission will check the file access permission requested in response to _Open or _OpenRF to see if it is possible using the Macintosh file system’s access permission model.
Before making this call, the foreign file system must determine what file number the open file will have. The file number along with the VCBPtr will allow UTCheckPermission to determine if the requested access permission will conflict with any other access paths to the file.
The foreign file system must also determine what values will be put into the fcbFlags and fcbTypByt fields of the FCBRec and supply those values to UTCheckPermission in the modByte parameterr; fcbFlags in the high byte, fcbTypByt in the low byte.
The bits for the fcbFlags byte should be set as follows
• The fcbWriteBit should be set if the requested permissions in the ioPermssn field of the parameter block are fsCurPerm, fsWrPerm, fsRdWrPerm, or fsRdWrShPerm.
• The fcbResourceBit should be set if responding to an _OpenRF request.
• The fcbSharedWriteBit should be set if the requested permissions in the ioPermssn field of the parameter block are fsRdWrShPerm.
• The fcbFileLockedBit should be set if the file is locked.
All other bits in in the fcbFlags field should be clear.
The fcbTypByt (used for the file version by the MFS file system) must be zero because the Resource Manager, Segment Loader, and Standard File Package won’t operate on files with non-zero version numbers.
If UTCheckPermission returns noErr, then the value returned in modByte contains the corrected values for fcbFlags and fcbTypByt and may be copied into the FCBRec for the new access path.
If UTCheckPermission returns opWrErr, then the file reference number of the existing exclusive-write path is returned in the ioRefNum field of the parameter block.
For a description of the Macintosh file system’s access permission model, see Inside Macintosh: Files pages 2-7 and 2-8 and the description of PBHOpen and PBHOpenRF on pages 2-184 through 2-186.
Result codes
noErr 0 No error
opWrErr -49 fsWrPerm, fsRdWrPerm, or fsRdWrShPerm
was requested on a file with an existing
exclusive-write access path
permErr -54 fsWrPerm, fsRdWrPerm, or fsRdWrShPerm
was requested on a locked file
UTCheckVolOffline
Use UTCheckVolOffline to make sure a volume reference number is valid and the volume is online.
pascal OSErr UTCheckVolOffline(short vRefNum);
vRefNum Contains the volume reference number.
UTCheckVolOffline will return noErr if a volume reference number is valid and the volume is online.
Result codes
noErr 0 No error
rfNumErr -51 The volume reference number is not valid
volOffLinErr -53 The volume is offline
UTCheckVolModifiable
Use UTCheckVolModifiable to see if a volume can be written to.
pascal OSErr UTCheckVolModifiable(short vRefNum);
vRefNum Contains the volume reference number.
UTCheckVolModifiable checks the volume’s vcbAtrb field in its VCB to determine if the volume is locked by hardware or software.
Result codes
noErr 0 No error
wPrErr -44 The volume is write protected by hardware
vLckdErr -46 The volume is locked by software
UTCheckFileModifiable
Use UTCheckFileModifiable to see if a file can be written to.
UTCheckFileModifiable checks the volume’s vcbAtrb field in its VCB to determine if the volume is locked by hardware or software and checks the file's fcbFlags in its FCBRec to determine if the file can be written to through the access path specified by fileRefNum.
Result codes
noErr 0 No error
wPrErr -44 The volume is write protected by hardware
vLckdErr -46 The volume is locked by software
wrPermErr -61 The file access path does not have write
permission
UTCheckDirBusy
Use UTCheckDirBusy to see if a directory is an open working directory.
volCtrlBlockPtr Contains a VCBPtr that specifies the volume the directory is on.
dirID Contains the directory ID.
UTCheckDirBusy checks to see if the directory specified by dirID is an open working directory on the volume specified by volCtrlBlockPtr.
Result codes
noErr 0 No error
fBsyErr -47 The directory is an open working directory
UTDetermineVol
Use UTDetermineVol to determine what volume a parameter block refers to and how that determination was made.
pascal OSErr UTDetermineVol(ParmBlkPtr paramBlock, short *status,
short *moreMatches, short *vRefNum,
VCBPtr *volCtrlBlockPtr);
paramBlock Contains a pointer to the parameter block to evaluate.
status Contains a pointer to a short. UTDetermineVol places the decisive factor used to determine what volume paramBlock refers to into the field referred to by this parameter. The status values returned are:
dtmvError = 0 could not determine volume
dtmvFullPathame = 1 determined by full pathname
dtmvVRefNum = 2 determined by volume
reference number
dtmvWDRefNum = 3 determined by working
directory reference number
dtmvDriveNum = 4 determined by drive number
dtmvDefault = 5 determined by default volume
moreMatches Contains a pointer to a short. If the volume was determined by full pathname and more than one mounted volume has the volume name passed by paramBlock, UTDetermineVol places a non-zero value (the length of the volume name) into the field referred to by this parameter. The value returned the field referred to by this parameter should be ignored if status is not dtmvFullPathame.
vRefNum Contains a pointer to a short. UTDetermineVol places the volume reference number into the field referred to by this parameter.
volCtrlBlockPtr Contains a pointer to an VCBPtr. UTDetermineVol places a pointer to the VCB into the field referred to by this parameter.
UTDetermineVol uses the parameter block pointed to by paramBlock to determine what volume to use and returns the decisive factor used to determine the volume. The decisive factor used to determine the volume along with the other contents of the parameter block are used to find the file or directory the parameter block refers to.
UTDetermineVol determines the volume by searching in the following order:
1 Full pathname - This method is used if ioNamePtr is not NULL and points to a full pathname (see Inside Macintosh: Files for the definition of a full pathname). The first component of the pathname pointed to by the ioNamePtr field in the parameter block is used as the volume name and UTDetermineVol attempts to find the volume by name.
2 Reference number - The ioVRefNum field in the parameter block is used to determine the volume. If ioVRefNum is zero, UTDetermineVol attempts to find the default volume (if the default volume is set up). If ioVRefNum is positive, UTDetermineVol attempts to find the volume by drive number. If ioVRefNum is negative, UTDetermineVol first attempts to find the volume by volume reference number and it that fails, then UTDetermineVol attempts to find the volume by working directory reference number
s Warning: The PBGetCatInfo and PBGetFInfo File Manager calls do not use the ioNamePtr field in a parameter block as an input when the ioFDirIndex field in a parameter block is non-zero. Before calling UTDetermineVol in these cases, you must save the value of ioNamePtr and set ioNamePtr to NULL so that UTDetermineVol will not attempt to determine the volume by full pathname. After calling UTDetermineVol, you must restore the original value in ioNamePtr. s
If the volume cannot be determined, UTDetermineVol will fail with paramErr and the field referred to by the status parameter will be set to dtmvError.
Result codes
noErr 0 No error
paramErr -50 The parameter block does not refer to a
mounted volume
UTParsePathname
Use UTParsePathname to detemine if a pathname is valid, if the pathname is a partial or full pathname, and the volume name length if the pathname is a full pathname.
volNamelength Contains a pointer to a short. If the pathname is a full pathname, UTParsePathname places the length of the volume name into the field referred to by this parameter. If the pathname is a partial pathname, UTParsePathname places zero into the field referred to by this parameter.
namePtr Contains a pointer to a Pascal string that specifies the pathname.
UTParsePathname determines if namePtr points to a valid pathname, if the pathname is a partial or full pathname, and the volume name length if the pathname is a full pathname. See Inside Macintosh: Files for the definition of a full and partial pathnames. UTParsePathname cannot parse pathnames with more than 31 consecutive colon separators.
Result codes
noErr 0 No error
bdNamErr -37 namePtr is NULL, namePtr points to a zero
length string, the pathname doesn’t have correct
syntax, or pathname has more than
31 consecutive colon separators
UTGetPathComponentName
Use UTGetPathComponentName to parse the components in a pathname.
Æ namePtr StringPtr Contains a pointer to a Pascal string that
contains the pathname.
Æ startOffset short Contains the offset into the pathname
where the parsing will begin. Offset 0
(not 1) is the first character of the
pathname.
¨ componentLength short UTGetPathComponentName places the
length of the component into this field.
¨ moreName short If there is no more pathname left after
the parse, UTGetPathComponentName
places zero into this field; otherwise, a
non-zero value is placed into this field.
¨ foundDelimiter short If parsing stops because a delimiter (a
colon character) is found,
UTGetPathComponentName places a
non-zero value into this field;
otherwise, zero is placed into this field.
UTGetPathComponentName parses a pathname to get the individual components that make up the pathname.
The namePtr field in the ParsePathRec passed to UTGetPathComponentName must point to the pathname to parse. The startOffset field in the ParsePathRec tells UTGetPathComponentName where to start looking for a pathname component.
UTGetPathComponentName returns the length of the component at startOffset in the componentLength field of the ParsePathRec, indicates if the parse found the end of the pathname in the moreName field of the ParsePathRec, and indicates if the parse stopped because a delimiter character was found.
Result codes
noErr 0 No error
bdNamErr -37 namePtr is NULL, namePtr points to a zero
length string, the pathname doesn’t have correct
syntax, or pathname has more than
31 consecutive colon separators
UTGetBlock
Use UTGetBlock to get a cache block in the Macintosh volume cache.
refNum Contains the file or volume reference number.
log2PhyProc Contains a pointer to the logical to physical routine or NULL if refNum is a volume refererence number.
blockNum Contains the logical block number of the file, or the physical block number of the volume.
gbOption Contains the get block options. The option values you can pass are:
gbDefault read from disk if block is not found in the
cache
gbRead always read block from disk (forced read)
gbExist get block only if it is already in the cache as a
released block.
gbNoRead do not read block if it is not already in the
cache
gbRelease this option can be added to any of the other
gbOptions to release the block immediately
after getting it
buffer Contains a pointer to a Ptr. UTGetBlock places the memory address of the cache block into the field referred to by this parameter.
UTGetBlock gets a cache block in the Macintosh volume cache and returns the address of the cache block in the buffer parameter. If refNum is a volume reference number, the blockNum is the physical block on the volume. If refNum is a file reference number, then GetBlock calls the logical to physical routine to map blockNum, the logical file block, to a physical block on the volume.
UTGetBlock lets you specify several options with the gbOption parameter:
• gbDefault should be used to get a disk block from the cache if it’s in the cache, or to bring a disk block into the cache if it isn’t in the cache.
• gbRead should be used to force a block to be read from from the disk. For example, you’d use the gbRead option when handling a _Read call where the read-verify mode is requested by the caller.
• gbNoRead should be used to get a cache block who’s contents will be completely overwritten.
• gbExist should be used for getting a disk block which should already be in the cache as a released block. A free cache blocks is not found if gbExist is specified. If UTGetBlock with the gbExists option fails, use UTBlockInFQHashP to see if a physical block on the volume is in a free cache block in the Macintosh volume cache and if so, retry UTGetBlock with the gbDefault option.
• gbRelease can be added to any of the other gbOptions to release the cache block immediately after getting it. This saves the step of releasing the block with UTReleaseBlock when you know you won’t be making another call to the Macintosh Volume Cache (which could reuse the cache block) before the cache block is used.
Important note: UTGetBlock can potentially return an internal positive error result code. Because the file system should never return a positive result, your foreign file system should return ioErr if it cannot recover gracefully from one of the positive error results.
s Warning: UTGetBlock may only be called from a foreign file system handling a request through its HFSCIProc. Attempts to call UTGetBlock outside of the context of the HFSCIProc will cause a system crash. s
chInUse 2 Cache internal error - requested block is
reserved
chNotfound 3 Cache internal error - requested block was not
found (only if gbExist option)
ioErr -36 Device I/O error
offLinErr -65 Device was offline
notEnoughMemoryErr -620 VM was not able to hold down enough
physical memory
UTReleaseBlock
Use UTReleaseBlock to release a reserved cache block.
pascal OSErr UTReleaseBlock(Ptr buffer, short rbOption);
buffer Contains a pointer to the cache block to release.
rbOption Contains the release block options. The option values you can pass are:
rbDefault release the cache block
rbWrite release, write the cache block to disk
(forced write) - this will also mark the cache
block clean
rbTrash mark the cache block trashed
rbDirty release and mark the cache block dirty
(deferred write)
rbFree mark the cache block free
UTReleaseBlock releases the reserved cache block specified in the buffer parameter. The rbOption parameter also allows UTReleaseBlock to write the cache block to disk, mark the cache block dirty, free the cache block, or trash the cache block.
Important note: UTReleaseBlock can potentially return an internal positive error result code. Because the file system should never return a positive result, your foreign file system should return ioErr if it cannot recover gracefully from the positive error result.
s Warning: UTReleaseBlock may only be called from a foreign file system handling a request through its HFSCIProc. Attempts to call UTReleaseBlock outside of the context of the HFSCIProc will cause a system crash. s
Result codes
noErr 0 No error
chNotInUse 1 Cache internal error - block being released was
not in use
ioErr -36 Device I/O error (only if rbWrite option)
offLinErr -65 Device was offline (only if rbWrite option)
notEnoughMemoryErr -620 VM was not able to hold down enough
physical memory (only if rbWrite option)
UTFlushCache
Use UTFlushCache to flush all dirty cache blocks associated with a file or volume.
pascal OSErr UTFlushCache(short refNum, short fcOption);
refNum Contains the file or volume reference number.
fcOption Contains the flush block options. The option values you can pass are:
fcDefault flush the cache blocks
fcTrash mark the cache blocks trashed after flushing
them
fcFree mark the cache blocks free after flushing
them
UTFlushCache flushes all dirty blocks associated with the file or volume specified by refNum. The fcOption parameter also allows UTFlushCache to free the cache blocks, or trash the cache blocks after flushing them.
Note: When the fcTrash or fcFree option is used, all cache blocks associated with the file or volume are trashed or freed - not just those blocks that were dirty and flushed.
s Warning: UTFlushCache may only be called from a foreign file system handling a request through its HFSCIProc. Attempts to call UTFlushCache outside of the context of the HFSCIProc will cause a system crash. s
Result codes
noErr 0 No error
UTMarkDirty
Use UTMarkDirty to mark a cache block dirty.
pascal OSErr UTMarkDirty(Ptr buffer);
buffer Contains a pointer to the cache block to mark dirty.
UTMarkDirty marks the specified cache block dirty.
Result codes
noErr 0 No error
UTTrashVolBlocks
Use UTTrashVolBlocks to trash all file and volume cache blocks associated with a volume.
volCtrlBlockPtr Contains a VCBPtr that specifies the volume.
UTTrashVolBlocks trashes all file and volume cache blocks associated with the volume specified by volCtrlBlockPtr. That includes all released blocks and all free blocks. This routine must be used when a volume is unmounted or ejected.
Result codes
noErr 0 No error
UTTrashFileBlocks
Use UTTrashFileBlocks to trash all cache blocks associated with a file.
volCtrlBlockPtr Contains a VCBPtr that specifies the volume the file is on.
fileNum Contains the file’s file number.
UTTrashFileBlocks trashes all cache blocks associated with the file specified by fileNum on the volume specified by volCtrlBlockPtr. This routine is typically used when a file is deleted.
Result codes
noErr 0 No error
UTTrashBlocks
Use UTTrashBlocks to trash or free a range of cache blocks associated with a file.
pascal OSErr UTTrashBlocks(unsigned long beginPosition,
unsigned long byteCount,
VCBPtr volCtrlBlockPtr, short fileRefNum,
short tbOption)
beginPosition Contains the beginning byte position of the blocks to trash. beginPosition must be a multiple of 512 bytes.
byteCount Contains the number of bytes to trash. byteCount must be a multiple of 512 bytes.
volCtrlBlockPtr Contains a VCBPtr that specifies the volume the file is on.
fileRefNum Contains the file’s reference number.
tbOption Contains the trash block options. If zero, the range of blocks if trashed; If non-zero, the range of blocks is marked free.
UTTrashBlocks trashes or frees a range of cache blocks associated with the file specified by fileRefNum on the volume specified by volCtrlBlockPtr. The range is specified by beginPosition and byteCount. This routine is typically used when a file is shortened.
Result codes
noErr 0 No error
UTCacheReadIP
Use UTCacheReadIP to read a consecutive number of blocks into the caller’s buffer.
pascal OSErr UTCacheReadIP(void *log2PhyProc,
unsigned long filePosition,
Ptr ioBuffer, short fileRefNum,
unsigned long reqCount,
unsigned long *actCount,
short cacheOption);
log2PhyProc Contains a pointer to the logical to physical mapping routine.
filePosition Contains the position in bytes to start reading from. This must fall on a 512-byte boundary (i.e., 0, 512, 1024, etc.).
ioBuffer Contains a pointer to data buffer where the data will be read.
fileRefNum Contains the file reference number.
reqCount Contains the number of bytes to read. This must be a multiple of 512 bytes.
actCount Contains a pointer to an unsigned long. UTCacheReadIP places the actual number of bytes read into the field referred to by this parameter .
cacheOption Contains the cache options. The valid bits in the cacheOption parameter are:
noCache please don’t cache this read
rdVerify always read blocks from disk (forced read)
UTCacheReadIP lets you request a multiple-block read from a file through the file system cache mechanism. UTCacheReadIP always reads a contiguous range of blocks. The number of contiguous blocks actually read is determined by the log2PhyProc and is returned in actCount.
The cacheOption parameter lets you request that reads not be cached, or that reads always come from the disk. A foreign file system handling a _Read call can simply use the ioPosMode word from the caller’s parameter block for the cacheOption parameter.
Important note: UTCacheReadIP can potentially return an internal positive error result code. Because the file system should never return a positive result, your foreign file system should return ioErr if it cannot recover gracefully from one of the positive error results.
s Warning: UTCacheReadIP may only be called from a foreign file system handling a request through its HFSCIProc. Attempts to call UTCacheReadIP outside of the context of the HFSCIProc will cause a system crash. s
chInUse 2 Cache internal error - requested block is
reserved
chNotfound 3 Cache internal error - requested block was not
found (only if gbExist option)
ioErr -36 Device I/O error
offLinErr -65 Device was offline
notEnoughMemoryErr -620 VM was not able to hold down enough
physical memory
UTCacheWriteIP
Use UTCacheWriteIP to write a consecutive number of blocks from the caller’s buffer.
pascal OSErr UTCacheWriteIP(void *log2PhyProc,
unsigned long filePosition, Ptr ioBuffer,
short fileRefNum, unsigned long reqCount,
unsigned long *actCount,
short cacheOption);
log2PhyProc Contains a pointer to the logical to physical mapping routine.
filePosition Contains the position in bytes to start writing to. This must fall on a 512-byte boundary (i.e., 0, 512, 1024, etc.).
ioBuffer Contains a pointer to data buffer containing the data.
fileRefNum Contains the file reference number.
reqCount Contains the number of bytes to write. This must be a multiple of 512 bytes.
actCount Contains a pointer to an unsigned long. UTCacheWriteIP places the actual number of bytes written into the field referred to by this parameter .
cacheOption Contains the cache options. The valid bits in the cacheOption parameter are:
noCache please don’t cache this write
UTCacheWriteIP lets you request a multiple-block write to a file through the file system cache mechanism. UTCacheWriteIP always writes a contiguous range of blocks. The number of contiguous blocks actually written is determined by the log2PhyProc and is returned in actCount.
The cacheOption parameter lets you request that writes not be cached. A foreign file system handling a _Write call can simply use the ioPosMode word from the caller’s parameter block for the cacheOption parameter.
Important note: UTCacheWriteIP can potentially return an internal positive error result code. Because the file system should never return a positive result, your foreign file system should return ioErr if it cannot recover gracefully from one of the positive error results.
s Warning: UTCacheWriteIP may only be called from a foreign file system handling a request through its HFSCIProc. Attempts to call UTCacheWriteIP outside of the context of the HFSCIProc will cause a system crash. s
chInUse 2 Cache internal error - requested block is
reserved
chNotfound 3 Cache internal error - requested block was not
found (only if gbExist option)
ioErr -36 Device I/O error
offLinErr -65 Device was offline
notEnoughMemoryErr -620 VM was not able to hold down enough
physical memory
UTBlockInFQHashP
Use UTBlockInFQHashP to see if a physical block on the volume is in a free cache block in the Macintosh volume cache.
pascal OSErr UTBlockInFQHashP(short vRefNum, unsigned long diskBlock);
vRefNum Contains the volume reference number.
diskBlock Contains the physical block number of the volume.
UTBlockInFQHashP lets you check to see if the specified block is in a free cache block in the Macintosh volume cache. UTBlockInFQHashP returns noErr if the disk block data is in a free cache block. A result of chNotfound indicates that the disk block is not in the free block queue (although it may in the cache as a reserved or released block).
Result codes
noErr 0 No error
chNotfound 3 Requested block was not found in the free
block queue
4 The Disk Initialization Component Interface
About this chapter
This chapter describes the Disk Initialization Package component interface, the data structures used by the Disk Initialization Package component interface, and the routines your foreign file system must provide to the Disk Initialization Package component interface.
To use this chapter, you should be familiar with the information in the chapter “The File System Manager” in this document, the information in Inside Macintosh: Files, the information in Inside Macintosh: Devices, and the information in the Technical Note “What Your Sony Drives for You”.
About the Disk Initialization Package component interface
The Disk Initialization Package component interface allows a foreign file system to process Disk Initialization Package requests and allows a foreign file system to describe its disk initialization services to the File System Manager. Whenever a Disk Initialization Package request is made, the File System Manager will call the foreign file system through the Disk Initialization Package component interface to get additional information and request specific actions.
Using the Disk Initialization Package component interface
This section describes
• the Disk Initialization Package Component Interface record
• the Disk Initialization Package Component Interface request processing function and its function selectors
The Disk Initialization Package Component Interface Record
The Disk Initialization Package component interface record in an File System Descriptor record lets the foreign file system tell the Disk Initialization Package component interface how to dispatch Disk Initialization Package requests to the foreign file system. It tells the Disk Initialization Package component interface where the routine to handle Disk Initialization Package requests is in memory, the maximum length of volume names the foreign file system can accept, and the disk block size of your foreign file system’s volume format. The data type DICIRec defines the Disk Initialization Package component interface record.
struct DICIRec {
long compInterfMask; /* component flags */
DICIUPP compInterfProc; /* pointer to request
processing code */
short maxVolNameLength; /* maximum length of your
volume name */
unsigned short blockSize; /* your file system's block
size */
long reserved3; /* --reserved, must be
zero-- */
long reserved2; /* --reserved, must be
zero-- */
long reserved1; /* --reserved, must be
zero-- */
};
typedef struct DICIRec DICIRec;
typedef DICIRec *DICIRecPtr;
Field descriptions
compInterfMask Contains the Disk Initialization Package component interface dispatch mask. Currently the following bits are defined:
Bit Meaning
0 diCILiveBit If set, this file system is a
candidate for the current
formatting operation. This bit is
maintained by the Disk
Initialization Package
component interface.
1-15 Reserved.
16 diCIDoesSparingBit Set this bit if the foreign file
system supports bad block disk
sparing.
17 diCIHasMultiVolTypesBit Set this bit if the foreign file
system supports more than one
volume type.
18 diCIHasExtFormatParamsBit Set this bit if the foreign file
system uses extended format
parameters.
19-23 Reserved.
24-29 Reserved for the File System
Manager’s use.
30 fsmComponentBusyBit If set, the FSM component
interface is busy (i.e., one or
more requests are outstanding).
This bit is maintained by the
component and used by the File
System Manager to control the
use of the SetFSInfo File
System Manager service request.
31 fsmComponentEnableBit If set, the component may begin
dispatching requests to the foreign
file system. The foreign file
system should set this bit with
the SetFSInfo File System
Manager service request once it is
ready to receive requests.
compInterfProc Contains a pointer to the foreign file system’s Disk Initialization Package component interface request processing function.
maxVolNameLength Contains the maximum length of volume names the foreign file system can accept.
blockSize Contains the size of the foreign file system disk block in bytes.
The Disk Initialization Package Component Interface Request Processing Function
The Disk Initialization Package Component Interface request processing function pointed to by compInterfProc in a DICIRec is called by the File System Manager to handle Disk Initialization Package requests. The Disk Initialization Package Component Interface request processing function must have the following form.
whatFunction Contains a selector number which indicates what operation the foreign file system must perform.
paramBlock Contains a pointer to the parameter block passed to the Disk Initialization Package component interface request processing function. The contents of the parameter block are specific to the selector number passed.
fsdGlobalPtr Contains a pointer to the foreign file system’s optional global data area.
When the foreign file system’s DICIProc is called, it is passed a function selector number which specifies the operation to perform, a pointer to a buffer containing any additional parameters needed to process the operation, and a pointer to the foreign file system’s global data area. The currently defined messages are listed in Table 4-1.
Table 4-1. Disk Initialization Package Component Interface Function Selectors
Message Purpose
diCILoad 1 Load the disk initialization code and data resources (if they are not loaded or purged) and make them unpurgable.
diCIUnload 2 Make the disk initialization code and data resources purgable.
diCIEvaluateSizeChoices 3 Determine if the foreign file system can initialize a disk in the specified drive.
diCIExtendedZero 4 Initialize a disk (write an empty volume directory).
diCIValidateVolName 5 Determine if a volume name is valid.
diCIGetVolTypeInfo 6 If the foreign file system supports more than one volume type, provide a list of those volume types.
diCIGetFormatString 7 Supply strings used to build the Format pop-up menu and help balloons used in the disk initialization dialog box.
diCIGetExtFormatParams 8 Query the user (or another part of the system) for additional formatting information beyond that supplied by the disk initialization dialog box provided by the Disk Initialization Package.
How the foreign file system’s DICIProc should handle each operation and what result codes should be returned are described in the following sections.
Note: The DICIProc cannot be called at interrupt time. Thus, it may make Memory Manager requests and synchronous operating system requests.
diCILoad
The diCILoad function selector tells the foreign file system to load the disk initialization code and data resources (if they are not loaded or purged) and make them unpurgable. The paramBlock parameter is not used with the diCILoad function selector.
Result codes
noErr 0 No error
any of the result codes returned by the Resource Manager, GetFSInfo, or SetFSInfo
diCIUnload
The diCIUnload function selector tells the foreign file system to make the disk initialization code and data resources purgable. The paramBlock parameter is not used with the diCIUnload function selector.
Result codes
noErr 0 No error
diCIEvaluateSizeChoices
The diCIEvaluateSizeChoices function selector allows a foreign file system to determine if it can initialize a disk in the specified drive. If the disk drive can format disks in more than one size, the foreign file system indicates what sizes it can support and the preferred size. The paramBlock parameter points to a DICIEvaluateSizeRec record.
DICIEvaluateSizeRec
¨ defaultSizeIndex short The foreign file system returns the index
number of the preferred or default SizeListRec
in this field; the first SizeListRec is at index
position 1. If none of the SizeListRec records
contain a valid size choice for the foreign file
system, return zero.
Æ numSizeEntries short Contains the number of SizeListRec records in
the array pointed to by sizeListPtr.
Æ driveNumber short Contains the drive number.
Æ sizeListPtr SizeListRecPtr Contains a pointer to an array of
SizeListRec records.
Æ sectorSize unsigned short Contains the number of bytes per sector
(sectors may not be the same size as blocks
used by a foreign file system). Use this value
to help determine if the foreign file system
can use disks mounted on this drive.
The sizeListPtr field in the DICIEvaluateSizeRec points to an array of SizeListRec records.
SizeListRec
¨ sizeListFlags short The foreign file system returns the size list
flags in this field. All bits are currently reserved
except:
diCISizeListOKBit Set this bit if the size
specified in sizeEntry
can be used by this
foreign file system.
Æ sizeEntry FormatListRec Contains a FormatListRec which specifies a
possible size of the drive.
The sizeEntry field in a SizeListRec is a FormatListRec.
FormatListRec
Æ volSize unsigned long Contains the disk capacity in disk sectors
(sectors may not be the same size as blocks
used by a foreign file system).
Æ formatFlags SignedByte Contains the format flags, density bit, and
number of disk sides. The sides,
sectorsPerTrack, and tracks are valid if
diCIFmtFlagsValidBit is set. The current disk
has this format if diCIFmtFlagsCurrentBit is
set. The disk is double-density (.SONY driver
only) if diCIFmtFlagsDoubleDensityBit is set.
The low nibble of the byte contains the number
of disk sides.
Æ sectorsPerTrack SignedByte Contains the average number of sectors per
track.
Æ tracks unsigned short Contains the number of disk tracks.
The array of SizeListRec records is built from information obtained from the disk driver. Specifically, the File System Manager obtains the SizeListRec records by calling the disk driver’s _Status function with csCode set to Return Format List (6). If the disk driver does not support the Return Format List request, a single SizeListRec is constructed from the information in the drive queue element.
The foreign file system must index through the array of SizeListRec records. The number of elements in the array is indicated by numSizeEntries. If the foreign file system can format the disk using the size specified by a particular SizeListRec, it sets the diCISizeListOKBit in the SizeListRec’s sizeListFlags field. SizeListRec records usable by the foreign file system are shown in the Format pop-up menu in the disk initialization dialog box.
The index of the preferred SizeListRec is returned in the DICIEvaluateSizeRec record’s defaultSizeIndex field where defaultSizeIndex is in the range 1 to numSizeEntries. This is the menu item shown in the Format pop-up menu in the disk initialization dialog box if the current disk is already owned by this foreign file system.
Result codes
noErr 0 No error
diCIExtendedZero
The diCIExtendedZero function selector allows a foreign file system to initialize a disk. The paramBlock parameter points to a DICIExtendedZeroRec record.
DICIExtendedZeroRec
Æ driveNumber short Contains the drive number of the device which
should be initialized with an empty volume
directory structure.
Æ volNamePtr StringPtr Contains a pointer to the name that the volume
should be given.
Æ fsid short Contains the target file system ID.
Æ volTypeSelector short Contains the volume type selector if the foreign
file system supports more than one volume
type (diCIHasMultiVolTypesBit is set in
the compInterfMask field of the DICIRec).
Æ numDefectBlocks unsigned short Contains the number of bad disk blocks or
zero. The block size is the size specified in the
blockSize field of the DICIRec.
Æ defectListSize unsigned short Contains the size of the defect list buffer if
numDefectBlocks is not zero. For example, if
the volume size is 800K and your file system’s
block size is 1024 bytes, then defectListSize =
100 (800 bits = 100 bytes) and the defect list
buffer is 100 bytes in size.
Æ defectListPtr Ptr Contains a pointer to the defect list buffer if
numDefectBlocks is not zero. The buffer
contains a bitmap of the disk blocks. A zero bit
means the block is good, and a one bit means
the block is defective. This buffer is allocated
by the Disk initialization Package and is
released by the Disk initialization Package after
returning from this request.
Æ volSize unsigned short Contains the size of the volume in disk sectors
(sectors may not be the same size as blocks
used by a foreign file system).
Æ sectorSize unsigned short Contains the number of bytes per disk sector
(sectors may not be the same size as blocks
used by a foreign file system).
Æ extendedInfoPtr Ptr Contains a pointer to the foreign file system’s
extended formatting information (if
diCIHasExtFormatParamsBit is set in the
compInterfMask field of the DICIRec), or nil.
The foreign file system must initialize the disk specified by driveNumber.
If the foreign file system has set diCIHasMultiVolTypesBit in the compInterfMask field of the DICIRec indicating that it supports multiple volume formats, the volume type selected is in volTypeSelector.
If the foreign file system has set diCIDoesSparingBit in the compInterfMask field of the DICIRec, it can use the information in numDefectBlocks, defectListSize, and defectListPtr to perform bad block sparing.
Result codes
noErr 0 No error
diCICriticalSectorBadErr 20 Disk cannot be spared; sectors critical to the
volume format are bad
diCISparingFailedErr 21 Disk cannot be spared; general error
diCITooManyBadSectorsErr 22 Disk cannot be spared; too many bad
sectors were found
diCIUnknownVolTypeErr 23 The volume type passed is not supported
diCINoExtendInfoErr 27 extendedInfoPtr was required but nil was
passed
paramErr -50 The file system ID passed does not belong to
this foreign file system
diCIValidateVolName
The diCIValidateVolName function selector allows a foreign file system to determine if a volume name is valid. The paramBlock parameter points to a DICIValidateVolNameRec record.
DICIValidateVolNameRec
Æ theChar char Contains the character to validate.
¨ hasMessageBuffer Boolean The foreign file system returns true in this field
if it is providing its own alert message when an
illegal character is detected (messageBufferPtr
must not be nil).
Æ charOffset short Contains the position of the current character
(the first character is at position 1).
´ messageBufferPtr StringPtr If messageBufferPtr is not nil, then it points to
a Str255 buffer where the foreign file system
can return its own alert message when an illegal
character is detected.
Æ charByteType short Contains the identity of theChar as a 1-byte
character or as the first or second byte of a 2-byte
character. The values can be:
smFirstByte First byte of a 2-byte character
smSingleByte 1-byte character
smLastByte Second byte of 2-byte character
smFirstByte, smSingleByte, and smLastByte are
defined in Script.h.
Foreign file systems must be able to determine if a volume name is valid. The volume name must be validated:
• as characters are entered into the name field in the disk initialization dialog box. This gives the foreign file system an opportunity to examine the syntax of the name as it is being assembled.
• when the volume format selected in the Format pop-up menu in the disk initialization dialog box changes. This gives the foreign file system an opportunity to examine the syntax of the name already entered in the the name field.
• when characters are pasted into the name field of the disk initialization dialog box. This gives the foreign file system an opportunity to examine the syntax of the characters added to the name.
If an illegal character is detected, the foreign file system must return paramErr.
If messageBufferPtr is not nil, then it points to Str255 buffer where the foreign file system can return its own alert message when an illegal character is detected. If an illegal character alert message is supplied, the foreign file system must return true in the hasMessageBuffer field. If hasMessageBuffer is left false, the Disk Initialization Package uses the default illegal character alert message. The messageBufferPtr field is set to nil (no buffer is provided) when the volume format selected in the Format pop-up menu in the disk initialization dialog box changes and when characters are pasted into the name field of the disk initialization dialog box.
The Disk Initialization Package ensures volume names are not too long.
Result codes
noErr 0 No error
paramErr -50 The character passed is illegal in this foreign
file system’s volume names
diCIGetVolTypeInfo
The diCIGetVolTypeInfo function selector allows a foreign file system that supports more than one volume type to provide a list of those volume types. The paramBlock parameter points to a DICIGetVolTypeInfoRec record.
DICIGetVolTypeInfoRec
Æ volSize unsigned long Contains the disk capacity in disk sectors
(sectors may not be the same size as blocks
used by a foreign file system).
Æ sectorSize unsigned short Contains the number of bytes per sector
(sectors may not be the same size as blocks
used by a foreign file system).
¨ numVolTypes short The foreign file system returns the number of
volume types it supports in this field.
¨ volTypesBuffer[4] Str32 The foreign file system returns the names of
volume types it supports in these string fields.
Some file systems support more than one volume type, for example Macintosh File System supports both HFS and MFS volume types. If your foreign file system supports more than one volume type, it should set the diCIHasMultiVolTypesBit in the compInterfMask field of its DICIRec. If the diCIHasMultiVolTypesBit is not set, the Disk Initialization Package Component Interface request processing function will not be called with the diCIGetVolTypeInfo function selector.
The volSize and sectorSize fields are provided to help the foreign file system determine which of its volume types can be used.
The foreign file system returns the number of volume types it supports in the numVolTypes field. Up to four volume types are allowed.
The name of each supported volume type is returned in one of the four volTypeBuffer string buffers. These strings are used, together with the file system name and disk size, to compose the menu item strings to be displayed in the disk initialization dialog’s Format pop-up menu. The order of the strings is important because the ordering number will be passed as the volTypeSelector to the foreign file system when it is called with the diCIExtendedZero function selector. The value of volTypeSelector is only meaningful to your file system as it is a direct mapping to the types returned by this function request in the volTypesBuffer string buffers.
Your foreign file system’s default volume type string must be returned in volTypesBuffer[1] for that volume type to be selected as the default in the Format pop-up menu in the disk initialization dialog box.
Your volume type information and the corresponding type selectors should be published in your foreign file system’s documentation so that specific volume types can be initialized programmatically by applications with the DIXZero function.
Result codes
noErr 0 No error
diCIGetFormatString
The diCIGetFormatString function selector allows a foreign file system to supply strings used to build the Format pop-up menu and help balloons used in the disk initialization dialog box. The paramBlock parameter points to a DICIGetFormatStringRec record.
DICIGetFormatStringRec
Æ volSize unsigned long Contains the disk capacity in disk sectors
(sectors may not be the same size as blocks
used by a foreign file system).
Æ sectorSize unsigned short Contains the number of bytes per sector
(sectors may not be the same size as blocks
used by a foreign file system).
Æ volTypeSelector short Contains the volume type selector if the foreign
file system supports more than one volume
type (diCIHasMultiVolTypesBit is set in
the compInterfMask field of the DICIRec).
Æ stringKind short Contains the kind of string requested. The
kinds are:
diCIAlternateFormatStr get the alternate
format string
diCISizePresentationStr get the size
presentation string
¨ stringBuffer Str255 The foreign file system returns the string
requested in this field.
A foreign file system can supply strings used to build the Format pop-up menu and help balloons used in the disk initialization dialog box. If the foreign file system doesn’t provide the string, it can return diCIUnknownDICallErr and Disk Initialization Package will use its default strings.
If stringKind is diCIAlternateFormatStr, the foreign file system can provide a string that will be used augment the help balloon displayed for a volume type in the Format pop-up menu in the disk initialization dialog box. For example, without the alternate format string, the balloon text for an Macintosh 800K disk reads “To erase the selected disk and change it to a Macintosh 800K disk, choose this item, then click Erase.” With the alternate format string “ (also known as a double-sided Macintosh disk)”, the balloon text for an Macintosh 800K disk reads “To erase the selected disk and change it to a Macintosh 800K disk (also known as a double-sided Macintosh disk), choose this item, then click Erase.”
If stringKind is diCISizePresentationStr, the foreign file system can provide a string that replaces the volume type in the Format pop-up menu in the disk initialization dialog box. For example, by supplying the size presentation string, the volume type string in the Format pop-up menu could be changed from “Macintosh 720K” to “Macintosh HFS Interchange Format”.
Result codes
noErr 0 No error
diCIUnknownDICallErr 25 The requested string isn’t provided by this
foreign file system
diCIGetExtFormatParams
The diCIGetExtFormatParams function selector allows a foreign file system a chance to query the user (or another part of the system) for additional formatting information beyond that supplied by the disk initialization dialog box provided by the Disk Initialization Package. The paramBlock parameter points to a DICIGetExtendedFormatRec record.
DICIGetExtendedFormatRec
Æ driveNumber short Contains the drive number of the device to be
initialized.
Æ volTypeSelector short Contains the volume type selector if the foreign
file system supports more than one volume
type (diCIHasMultiVolTypesBit is set in
the compInterfMask field of the DICIRec).
Æ volSize unsigned long Contains the disk capacity in disk sectors
(sectors may not be the same size as blocks
used by a foreign file system).
Æ sectorSize unsigned short Contains the number of bytes per sector
(sectors may not be the same size as blocks
used by a foreign file system).
Æ fileSystemSpecPtr FSSpecPtr Contains a pointer to foreign file system’s
FSSpec.
¨ extendedInfoPtr Ptr The foreign file system returns a pointer to the
extended formatting information in this field.
A foreign file system may need more information from the user (or another part of the system) than can be provided by the disk initialization dialog box. The diCIGetExtFormatParams function selector allows a foreign file system a chance to query the user for extended formatting information after the user selects the Erase or Initialize button in the disk initialization dialog box. The diCIGetExtFormatParams function selector is called if the diCIHasExtFormatParamsBit is set in the compInterfMask field of the foreign file system’s DICIRec.
When called with the diCIGetExtFormatParams function selector, the foreign file system should allocate memory (if it hasn’t done so when called with the diLoad function selector) for the extended formatting information structure, open its resource fork using the FSSpec passed in the fileSystemSpecPtr field, display one or more dialogs to collect the extended information, close its resource fork, and then return a pointer to the extended formatting information in the extendedInfoPtr field. When called with the diUnload function selector, the foreign file system should dispose of its extended formatting information structure.
Any dialogs displayed should contain both a “Continue” and a “Cancel” button with the “Continue” button as the default selection. If the “Continue” button is selected, noErr should be returned as the result along with the extended formatting information. If the “Cancel” button is selected, diCIUserCancelErr should be returned as the result.
The extended formatting information data structure used by your foreign file system should be documented so that application programs can pass the information programmatically in the DIXZero request.
Result codes
noErr 0 No error
diCIUserCancelErr 1 The “Cancel” button was selected by the user
Appendix A: The Extended Disk Initialization Package
About this Appendix
This appendix documents three Disk Initialization Package functions not found in Inside Macintosh: Files.
Application Program Interface
The existing application program interface to the Disk Initialization Package as described in Inside Macintosh: Files will continue to be supported by the enhanced Disk Initialization Package. Applications which wish to initialize only Macintosh disks will continue to work and will require no changes. However, if an application wants to initialize non-Macintosh disks, it must use the new extended DIXFormat and DIXZero calls as described below.
Extended programmatic interfaces to media formatting and volume initialization functions are required such that applications may specify additional information for the overall formatting operation. This information corresponds to the new items in the user interface described in the previous section: file system type and disk size. The extended programmatic interface adds three new functions to the Disk Initialization Package called DIXFormat and DIXZero (for extended DIFormat and DIZero), and DIReformat.
Warning: Applications should insure that the extended Disk Initialization Package functions are present before making the DIXFormat, DIXZero, or DIReformat calls. This is done by calling Gestalt with the gestaltFSAttr selector. The extended Disk Initialization Package functions is available if the Gestalt function returns a result of noErr and the gestaltHasExtendedDiskInitbit (bit 6) is set in the response parameter. Due to the nature of older versions of the Disk Initialization Package, making the extended requests when they are not available may cause a system crash.
Listing 5-1 illustrates how you use Gestalt to determine if the extended Disk Initialization Package functions are available.
Listing 5-1. Testing for extended Disk Initialization Package functions
drvNum Contains the driver number of the drive to format.
fmtFlag Contains a boolean value which specifies the meaning of the fmtArg paramter.
fmtArg If fmtFlag is true, fmtArg specifies the actual value to be passed to the disk driver in the csParam field of the parameter block when the “format” _Control call is made to initialize the disk media. (The value is an index into the size list. For an explanation of appropriate values for this parameter, see the Technical Note “What Your Sony Drives For You”.)
If fmtFlag is false, fmtArg specifies the desired size of the media in number of 512-byte blocks. The disk driver is called to get possible sizes and the values in an to attempt to match the requested size. If more than one size list entry exists for the same size, the first entry in the list returned by the driver that best matches the fmtArg parameter will be used. For more information about the size list, see the Technical Note “What Your Sony Drives For You”. If the specified size is larger than the largest size in the size list returned by the driver, then the largest size will be used and that size is returned in actSize. If the specified size is smaller than the smallest size in the size list returned by the driver, then the smallest size will be used and that size is returned in actSize. For a specified value that is in between and without an exact match, the value closest to and smaller than the requested size is used.
actSize Contains a pointer to an unsigned long. Upon completion of a successful formatting operation, DIXFormat places the actual size of the formatted media in number of 512-byte blocks into the field referred to by this parameter.
The formatting of file systems requiring specific media formats should be done by specifying those media formats explicitly and not by counting on disk size alone. Foreign file systems with specific media requirements should use the driver specific information in the size list or should make appropriate driver _Status calls for additional information when called upon to “evaluate the size list”.
As in DIFormat, DIXFormat does not unmount the volume. You have to unmount the volume before issuing this call if necessary. If the volume has not been unmounted, then DIXFormat will return volOnLinErr error.
Result codes
noErr 0 No error
volOnLinErr -55 Volume is online
lastDskErr -64 Last of the range of low-level disk errors
...
firstDskErr -84 First of the range of low-level disk errors
DIXZero
The DIXZero function performs the same function as the DIZero function except that the file system, format result, volume type, volume size and extended formatting information may be specified.
pascal OSErr DIXZero(short drvNum, ConstStr255Param volName, short fsid,
short mediaStatus, short volTypeSelector,
unsigned long volSize, void *extendedInfoPtr);
drvNum Contains the driver number of the drive to initialize.
volName Contains a pointer to a Pascal string which specifies the name of the volume.
fsid Contains the ID of the file system whose format should be written to the disk. The file system ID can be obtained using the File System Manager GetFSInfo function.
mediaStatus Contains a flag to indicate the status of the disk media. Its value is the result code returned from the DIVerify function. If mediaStatus is non-zero, then the disk contains bad sectors and needs to be spared. If the file system specified doesn’t support bad block sparing (the diCIDoesSparingBit in the compInterfMask field of the DICIRec is clear), the Disk Initialization Package will just return this value as the function result. If the file system supports bad block sparing, then the Disk Initialization Package will gather the defect list and pass it to the file system.
volTypeSelector Contains the volume type selector if the foreign file system supports more than one volume type (diCIHasMultiVolTypesBit is set in the compInterfMask field of the file system’s DICIRec).
volSize Contains the size in 512-byte blocks of the file system that should be written to the drive specified by drvNum. This is the size returned in the actSize field by DIXFormat - the amount of space usable by a file system on the specified drive as it is currently formatted. If the specified size doesn't match with the current disk format size, DIXZero will return diCIVolSizeMismatchErr.
fsParams Contains a pointer to the foreign file system’s extended formatting information (if diCIHasExtFormatParamsBit is set in the compInterfMask field of the DICIRec), or nil.
As in DIZero, DIXZero does not unmount the volume but it will, however, mount the volume if the operation is successful. You have to unmount the volume before issuing this call if necessary. If the volume is mounted when DIZero or DIXZero is called, then a volOnLinErr error will be returned.
Result codes
noErr 0 No error
ioErr -36 I/O error
paramErr -50 Drive number specified is bad
volOnLinErr -55 Volume is already online
nsDrvErr -56 No such drive
lastDskErr -64 Last of the range of low-level disk errors
...
firstDskErr -84 First of the range of low-level disk errors
memFullErr -108 Not enough memory
DIReformat
The DIReformat function reformats disk volume.
pascal OSErr DIReformat(short drvNum, short fsid,
ConstStr255Param volName,
ConstStr255Param msgText);
drvNum Contains the driver number of the drive to format.
fsid Contains the ID of the file system whose format should be written to the disk. The file system ID can be obtained using the File System Manager GetFSInfo function.
volName Contains a pointer to a Pascal string which specifies the name of the volume.
msgText Contains a pointer to a Pascal string which specifies the explanatory text to be displayed in the disk initialization dialog box.
In the past, reformatting disk was accomplished by calling the DIBadMount function with the high word of the evtMessage parameter set to noErr and the explanatory text was set with the ParamText function. The DIReformat function provides the caller the ability to provide the explanatory text, the default file system ID, and the default name for the reformatted disk.
Note: The volume in the drive specified by drvNum must be mounted when calling DIReformat .
Result codes
noErr 0 No error
diCINoMessageTextErr 28 msgText was not provided
paramErr -50 Drive number specified is bad
nsDrvErr -56 No such drive
lastDskErr -64 Last of the range of low-level disk errors
...
firstDskErr -84 First of the range of low-level disk errors
memFullErr -108 Not enough memory
Appendix B: Additional File Manager Routines
About this Appendix
This appendix documents two File Manager routines that are not in Inside Macintosh: Files but must be documented for foreign file systems.
Application Program Interface
The following two functions, PBHUnmountVol and PBGetXCatInfo are not documented in Inside Macintosh: Files. Foreign file systems must respond correctly to PBHUnmountVol and may want to support PBGetXCatInfo. Applications may use PBGetXCatInfo, but must never call PBHUnmountVol.
s Warning: PBHUnmountVol is reserved for use only by the Macintosh operating system. The operating system uses PBHUnmountVol to unconditionally unmount volumes before system shutdown or restart. Applications should never call PBHUnmountVol because PBHUnmountVol can close files in use by other applications which can cause data loss or media corruption. s
PBHUnmountVol
The PBHUnmountVol function unconditionally unmounts a volume
Æ ioVRefNum short A volume reference number, a working directory
reference number, drive number, or 0 for the
default volume.
The PBHUnmountVol function unconditionally unmounts the specified volume. All user files on the volume will be closed by the file system owning the volume.
The PBHUnmountVol function always executes synchronously.
s Warning: PBHUnmountVol is reserved for use only by the Macintosh operating system. The operating system uses PBHUnmountVol to unconditionally unmount volumes before system shutdown or restart. Applications should never call PBHUnmountVol because PBHUnmountVol can close files in use by other applications which can cause data loss or media corruption. s
ASSEMBLY-LANGUAGE INFORMATION
The trap word for PBHUnmountVol is A20E.
Result codes
noErr 0 No error
nsvErr –35 No such volume reference number
ioErr –36 I/O error
bdNamErr –37 Bad volume name
paramErr –50 No default volume
nsDrvErr –56 No such drive
extFSErr –58 No file system claimed the volume
PBGetXCatInfo
You can use the PBGetXCatInfo function to get the short name (MS-DOS format name) and ProDOS information for files and directories.
Æ ioCompletion StringPtr Contains a pointer to PBGetXCatInfoAsync’s
completion routine.
¨ ioResult OSErr PBGetXCatInfo places its result code into this
field.
Æ ioNamePtr StringPtr Contains a pointer to the object name, or nil when
ioDirID specifies a directory that’s the object.
Æ ioVRefNum short Contains a volume specification.
Æ ioShortNamePtr OSErr Contains a pointer to a Pascal string buffer
(minimum 13 bytes). PBGetXCatInfo places
the short name into the field referred to by this
parameter. ioShortNamePtr cannot be nil.
¨ ioPDType short PBGetXCatInfo places the ProDOS file type into
this field.
¨ ioPDAuxType long PBGetXCatInfo places the ProDOS auxiliary
type into this field.
Æ ioDirID long Contains a directory ID.
PBGetXCatInfo returns the short name (MS-DOS format name) and ProDOS file/auxiliary type information for files and directories on volumes that support this function. Volumes that support PBGetXCatInfo will have the bHasShortName bit set in the vMAttrib field returned by PBHGetVolParms.
The following data structure and inline glue code is needed for applications that wish to use PBGetXCatInfo.
struct XCInfoPBRec {
QElemPtr qLink;
short qType;
short ioTrap;
Ptr ioCmdAddr;
ProcPtr ioCompletion; /* A pointer to a completion
routine */
OSErr ioResult; /* The result code of the
function */
StringPtr ioNamePtr; /* Pointer to object name or
nil */
short ioVRefNum; /* A volume specification */
long filler1;
StringPtr ioShortNamePtr; /* A pointer to the short name
For more information about short names and ProDOS file/auxiliary types, see Inside AppleTalk, second edition, Chapter 13 AppleTalk Filing Protocol, and the Apple II File Type Notes.
ASSEMBLY-LANGUAGE INFORMATION
The PBGetXCatInfo function uses routine selector $003A of HFSDispatch.
Result codes
noErr 0 No error
nsvErr -35 No such volume
fnfErr -43 File not found
paramErr -50 Function not supported by volume
dirNFErr -120 Directory not found
Appendix C: File System Routine Table
About this Appendix
This appendix lists all File Manager routine and the select codes that your foreign file system’s HFSCIProc can be called with.
Routine
Name Select
Code Required Volume
Attributes Notes
File Manager Traps
Open $A000 •
Close $A001 •
Read $A002 •
Write $A003 •
GetVolInfo $A007 •
Create $A008 •
Delete $A009 •
OpenRF $A00A •
Rename $A00B •
GetFileInfo $A00C •
SetFileInfo $A00D •
UnmountVol $A00E •
MountVol $A00F •
Allocate $A010 •
GetEOF $A011 •
SetEOF $A012 •
FlushVol $A013 •
GetVol $A014
SetVol $A015
FInitQueue $A016 Never passed to foreign file systems.
Eject $A017 •
GetFPos $A018 •
Offline $A035 •
SetFilLock $A041 •
RstFilLock $A042 •
SetFilType $A043 • This call is obsolete, but it does get passed to foreign file systems. You should return paramErr.
SetFPos $A044 •
FlushFile $A045 •
HFS Calls
HOpen $A200 •
HGetVInfo $A207 •
HCreate $A208 •
HDelete $A209 •
HOpenRF $A20A •
HRename $A20B •
HGetFileInfo $A20C •
HSetFileInfo $A20D •
HUnmountVol $A20E • Warning: reserved for system use only at system shutdown or restart! HUnmount unmounts a volume, even if files are open on the volume. The foreign file system should flush and close all open files before unmounting the volume.
AllocContig $A210 •
HGetVol $A214
HSetVol $A215
HSetFLock $A241 •
HRstFLock $A242 •
HFS Dispatch Calls
OpenWD $0001 •
CloseWD $0002
CatMove $0005 •
DirCreate $0006 •
GetWDInfo $0007
GetFCBInfo $0008 •
GetCatInfo $0009 •
SetCatInfo $000A •
SetVolInfo $000B •
LockRng $0010 •
UnlockRng $0011 •
CreateFileIDRef $0014 bHasFileIDs
DeleteFileIDRef $0015 bHasFileIDs
ResolveFileIDRef $0016 bHasFileIDs
ExchangeFiles $0017 bHasFileIDs
CatSearch $0018 bHasCatSearch
OpenDF $001A Never passed to foreign file systems. The foreign file system will only see Open and HOpen.
MakeFSSpec $001B If your foreign file system doesn't handle MakeFSSpec, the Macintosh file system will make the FSSpec by determining the real vRefNum and real parent dirID, and then indexing through the parent directory until a matching name is found. This can be *very* slow if the directory has a lot of entries or if your foreign file system implementation of GetCatInfo is slow. If you don’t support MakeFSSpec, return paramErr.
Desktop Manager Calls
DTGetPath $0020 bHasDesktopMgr The returned ioDTRefNum must be a file reference number (a FCB must be used).
DTCloseDown $0021 bHasDesktopMgr
DTAddIcon $0022 bHasDesktopMgr
DTGetIcon $0023 bHasDesktopMgr
DTGetIconInfo $0024 bHasDesktopMgr
DTAddAPPL $0025 bHasDesktopMgr
DTRemoveAPPL $0026 bHasDesktopMgr
DTGetAPPL $0027 bHasDesktopMgr
DTSetComment $0028 bHasDesktopMgr
DTRemoveComment $0029 bHasDesktopMgr
DTGetComment $002A bHasDesktopMgr
DTFlush $002B bHasDesktopMgr Do nothing (noErr) on remote shared volumes.
DTReset $002C bHasDesktopMgr Do nothing (noErr) on remote shared volumes.
DTGetInfo $002D bHasDesktopMgr Return paramErr on remote shared volumes.
DTOpenInform $002E bHasDesktopMgr The returned ioDTRefNum must be a file reference number (a FCB must be used). Return paramErr on remote shared volumes.
DTDelete $002F bHasDesktopMgr Return paramErr on remote shared volumes.
AppleShare Calls
GetVolParms $0030 • (see Note) GetVolParms is required if you want to support any of the calls that require a volume attribute bit.
GetLogInInfo $0031 bAccessCntl
GetDirAccess $0032 bAccessCntl
SetDirAccess $0033 bAccessCntl
MapID $0034 bAccessCntl
MapName $0035 bAccessCntl
CopyFile $0036 bHasCopyFile
MoveRename $0037 bHasMoveRename
OpenDeny $0038 bHasOpenDeny
OpenRFDeny $0039 bHasOpenDeny
GetXCatInfo $003A bHasShortName
GetVolMountInfoSize $003F
GetVolMountInfo $0040
VolumeMount $0041
Share $0042 Handled by AppleShare or File Sharing server.
UnShare $0043 Handled by AppleShare or File Sharing server.
GetUGEntry $0044 Handled by AppleShare or File Sharing server.
GetForeignPrivs $0060
SetForeignPrivs $0061
Appendix D: File System Manager Questions and Answers
About this Appendix
This appendix contains a bunch of questions and answers gathered by Developer Support that will be useful to developers of foreign file systems.
Questions and Answers
Q: If my foreign file system doesn’t support one of the non-required HFSDispatch select codes, what should it return?
A: The foreign file system should return paramErr (-50) if it doesn’t support one of the non-required HFSDispatch select codes.
Q: I’m implementing the Desktop Manager calls. How big can icons get?
A: Apple’s Desktop Manager allows icons to be up to 4500 bytes, you should too.
Q: What fields in an FCBRec can be used by a foreign file system for its own purposes?
A: See Chapter 3, The File System Utility Routines, of the Guide to the File System Manager. It tells what fields can be used by your foreign file system and tells how those fields are used by the HFS file system.
Q: What are the catalog node ID (CNID) numbers below fsUsrCNID (16) used for?
A: CNID 1 is reserved for the parent ID of the root directory (fsRtParID) and CNID 2 is reserved for the directory ID of the root directory (fsRtDirID). On HFS volumes, 3 is used for the extents file, 4 is used for the catalog file, and 5 is used for the bad allocation block file. Your foreign file system can use CNIDs 5 through 15 for whatever purposes it needs.
When _UnmountVol is called, the File Manager checks to see if there are any open files on that volume with a file number (fcbFlNm in the FCBRec) of fsUsrCNID or greater. If so, the File Manager does not pass the _UnmountVol request on to the file system that owns the volume and a result of fBsyErr is returned to the caller. You can use CNIDs 5 through 15 for files opened by your foreign file system that should not prevent _UnmountVol from succeeding (for example, you should use a CNID below fsUsrCNID for the file number in FCBRecs used for the Desktop Manager DTGetPath or DTOpenInform routines).
Q: What are the advantages of supporting the Desktop Manager select codes?
A: If you don’t support the Desktop Manager select codes, the Finder will attempt to create a Desktop file to keep track of application mappings and icons. The advantages of the Desktop Manager over the Desktop file are:
• There is a documented interface for the Desktop Manager functions that developers can use.
• The Desktop Manager can be used on shared volumes. The Desktop file, since it is simply a resource file, can only allow write access to one user or process - it cannot be shared. Under System 7, that process is the Finder.
• The Desktop Manager functions can be implemented by an external file system in the most efficient way possible for that particular file system.
• The Desktop Manager doesn't have the file size limitations imposed by the Resource Manager; 2727 resources and approximately 16Mb of resource data.
Q: How does information get removed from the Desktop file or Desktop Database?
A: With both the Desktop file and the Desktop Manager database, icon data is not removed from the database unless the Desktop database or file is rebuilt from scratch. That's because the Finder (and file system for that matter) has no way of being notified when the last file of a given creator and type is removed from a volume. If the Finder removes an application (a file with type APPL), then the Finder attempts to remove the application mapping information for that copy of the application from the Desktop database or file.
Q: We want to provide the shared desktop database environment. What minimal set of calls do we need to support for this?
A: It really depends on how your file system is going to be used. Apple's read-only foreign file systems such as ISO 9660 let you open the desktop database, get info on it (all zeros are returned), and get comments on the root directory. All other Desktop Manager routines return an error. Apple's two read/write file systems that support the Desktop Manager, AppleShare and HFS, both support all of the original Desktop Manager calls (selectors $20 through $2A). HFS supports the selectors $2B through $2F; DTFlush, DTReset, DTGetInfo, DTOpenInform, and DTDelete don't make sense in a shared environment. So, I'd say you need to support selectors $20 through $2A and then return an appropriate error for the others. AppleShare returns noErr and does nothing for DTFlush and DTReset and returns paramErr for DTGetInfo, DTOpenInform, and DTDelete.
Q: We do not necessarily want full AppleShare (AFP) access-control, but we need more information on foreign file privilege models.
A: To be compatible with existing Macintosh applications, you must mimic the HFS file system's permission model. Inside Macintosh: Files describes how AppleShare does that on pages 2-17 and 2-18. If you want a more extensive permission model that AppleShare-aware applications can use, then you'll need to support the AppleShare HFSDispatch selectors and mimic AppleShare permissions. If you can't fit into the AppleShare model, you can come up with your own model and use PBGetForeignPrivs and PBSetForeignPrivs to manipulate your native privileges. However, you still must map those privileges to the HFS file system model. If you decide to use PBGetForeignPrivs and PBSetForeignPrivs, you'll use the creator type assigned to your foreign file system for your vMForeignPrivID number (the number you return for PBHGetVolParms requests).
Q: What is needed for a foreign file system to support PBCatSearch?
A: You'll need to support PBHGetVolParms so that you can indicate that you support CatSearch. It will be up to your foreign file system to come up with a fast way to search a volume’s catalog for matches. The Apple Developer Support sample code MoreFiles version 1.2 and later contains much of the code needed to implement CatSearch in the file Search.C.
Q: FindFolder seems to make some assumption on volumes that support AppleShare (AFP) access-control. What are those assuptions?
A: The folder manager assumes that user ID 0 is the guest user and user ID 1 is the administrator (owner) user and uses byte range locks on an empty data file as a semaphore to control access to individual trash folders on the volume. For more information, see Inside AppleTalk, second edition and the AppleTalk Filing Protocol Version 2.1 chapter of the AppleShare 3.0 Developer’s Kit.
Q: How should I handle VolumeMount requests?
A: VolumeMount requests are caught by the File System Manager before they are passed to the File Manager. FSM calls each installed foreign file system’s fileSystemCommProc with a ffsIDVolMountMessage. If the media type is not your foreign file system’s media type, you return extFSErr. If the media type is your foreign file system’s media type, you return noErr and the your HFSCIProc will be called with the VolumeMount select code.
When your HFSCIProc is called with the VolumeMount select code, your foreign file system should do everything needed to mount a volume. It should:
• Allocate memory for a volume control block (VCB) with UTAllocateVCB.
• Fill in the fields of the VCB.
• Allocate memory for a drive queue element (DrvQEl) in the system heap.
• Fill in the fields of the DrvQEl.
• Call _AddDrive to add the DrvQEl to the drive queue (DrvQHdr).
• Add the VCB to the VCB queue (VCBQHdr) with UTAddNewVCB.
• Use PostEvent to post a diskInsertEvt event.
The volume reference number you return to VolumeMount is the volume reference number returned by UTAddNewVCB.
After VolumeMount returns to the caller, the Event Manager will handle the diskInsertEvt event and will call your foreign file system with a _MountVol request. Since the volume is already mounted, your MountVol code only needs to return noErr.
Q: Can I put up an additional user authentication dialog when my foreign file system gets a VolumeMount request?
A: You put up an additional user authentication dialog if the caller of VolumeMount tells you it is safe to do that. To allow foreign file system to determine if it is safe, Apple has extended the VolMountInfoHeader record to include a flags word (the same flags word already in the AFPVolMountInfo record). By setting the volMountInteractBit (bit 15) in the flags word, the caller can tell your foreign file system that it is safe to use the Dialog Manager to put up your authentication dialog. In addition, if your foreign file system finds that the VolMountInfo record passed is usable but needs to be updated, it can set the volMountChangedBit (bit 14) in the flags word to tell the caller that it needs to update the VolMountInfo record using the PBGetVolMountInfoSize and PBGetVolMountInfo functions.
The Alias Manager has been updated to set the volMountInteractBit if the kARMNoUI rule is passed to the MatchAlias function, and to return the state of the volMountChangedBit in the needsUpdate parameter of the MatchAlias function and the wasChanged parameter the ResolveAlias function.
Here are the new constant definitions and data types you need:
/* The new volume mount flags */
enum {
volMountInteractBit = 15, /* Input to VolumeMount: If
set, it's OK for the file
system to perform user
interaction to mount the
volume */
volMountInteractMask = 0x8000,
volMountChangedBit = 14, /* Output from VoumeMount: If
set, the volume was mounted,
but the volume mounting
information record needs to
be updated. */
volMountChangedMask = 0x4000,
volMountFSReservedMask = 0x00ff, /* bits 0-7 are defined each
file system's use */
volMountSysReservedMask = 0xff00 /* bits 8-15 are reserved for
Q: What is the correct time to put up an additional user authentication dialog when my foreign file system gets a VolumeMount request?
A: The correct time to put up an additional user authentication dialog is when your foreign file system’s fileSystemCommProc gets the ffsIDVolMountMessage. You don’t want to wait until your HFSCIProc is called because at that time, you’re in the middle of a File Manager request and cannot do anything that might cause another File Manager request.
Q: How do I register a VolumeMount media type? How do I register a foreign privileges ID number?
A: Use your file system ID number for your foreign privileges ID number and use the creator type that you registered for your file system ID number for the VolumMount media type. If for some reason, you need another VolumeMount media type or foreign privileges ID number, you can simply register another file system ID number. It will be up to you to document your file system ID number, foreign privileges ID number, and VolumeMount media type if you want developers to know about them. That’s keeping with Apple’s policy of keeping creator types, card ID numbers, ADEV ID numbers, etc. confidential. If you decide to publish information specific to your file system, you should probably include header files for programmers and that’s where you can document your numbers.
Q: Where are the constants for the new information I can get by calling Gestalt with the gestaltFSAttr selector?
A: Right here:
gestaltFSAttr = 'fs ', /* file system attributes */
gestaltFullExtFSDispatching = 0, /* all HFSDispatch selectors
are passed through to file
systems */
gestaltHasFSSpecCalls = 1, /* File Manager has FSSpec
calls */
gestaltHasFileSystemManager = 2, /* has the File System
Manager */
gestaltFSMDoesDynamicLoad = 3, /* File System Manager supports
dynamic loading */
gestaltFSSupports4GBVols = 4, /* file system supports
4 gigabyte volumes */
gestaltFSSupports2TBVols = 5, /* file system supports
2 terabyte volumes */
gestaltHasExtendedDiskInit = 6, /* has extended Disk
Initialization calls */
Q: What should I return when called with the GetVolParms HFSDispatch select code?
A: Funny you should ask. Here’s how GetVolParms looks from the file system side of things:
The GetVolParmsInfoBuffer Record from file systems implementing PBHGetVolParms:
Offset Field Meaning
0 vMVersion Version number of the GetVolParmsInfoBuffer
record you return. Version 1 indicates you can
return the vMVersion through vMServerAdr
fields. Version 2 indicates you can return the
vMVersion through vMForeignPrivID fields.
Note: You must return no more than ioReqCount
bytes to PBHGetVolParms requests. Indicate the
actual number of bytes returned in ioActCount.
2 vMAttrib A 32-bit quantity that encodes information about
the volume attributes.
6 vMLocalHand If supplied, a handle to private data kept by the
Macintosh system for shared volumes while they
are mounted. When you mount the volume, you
must allocate a handle to a 2-byte block of memory
in the system heap which is returned in
vMLocalHand. When you unmount the volume,
dispose of the handle. Set the bLocalWList bit in
the vMAttrib field to indicate that this field is valid.
See the description of bLocalWList for when you
should supply the handle.
10 vMServerAdr For file server volumes, this field contains the
AppleTalk internet address of the file server that
manages the volume. An application can inspect
this field to tell which volumes belong to a
particular file server; the value of this field is 0 if
the volume does not belong to a file server. If you
support PBHCopyFile, you must initialize this
field.
The Finder uses this field to determine if a volume
is a network volume (non-zero = network
volume). If you have a network volume that
doesn’t have an AppleTalk address, you need to
use something that isn't zero and isn't a valid
AppleTalk address - I suggest that you use
$ffffffff (-1); $ffffffff is an illegal AppleTalk
address so it won’t ever be used as a real
AppleTalk address.
14 vMVolumeGrade The relative speed rating of the volume. The scale
used to determine these values is currently
uncalibrated, so until further notice, return 0 in
this field.
18 vMForeignPrivID The access privilege model supported by the
volume. Currently two values are defined for this
field: 0 represents a standard HFS volume that
might or might not support the AFP privilege
model; fsUnixPriv represents a volume that
supports the A/UX privilege model. I recommend
that you use 0 and try to map your privilege model
to the AFP privilege model for maximum
compatibility with Macintosh applications.
The vMAttrib Field Bits from file systems implementing PBHGetVolParms:
Bit Name Meaning
31 bLimitFCBs The volume supports a small finite number of
open files. Set this bit to indicate that applications
should attempt to limit the number of files they
keep open on this volume. For example, the
Finder limits the number of file control blocks
used during copying to 8 instead of 16 if this bit is
set.
30 bLocalWList Set this bit to indicate that the vMLocalHand field
of the GetVolParmsInfoBuffer record is valid and
the Finder’s open window list information is not
stored on this volume. Shared volumes should set
this bit.
29 bNoMiniFndr Reserved; always set to 1.
28 bNoVNEdit This volume’s name cannot be edited. The
System 7 Finder ignores this bit and looks at
bAccessCntl instead for some reason.
27 bNoLclSync Set this bit to indicate that modification dates on
this volume can change with no action from this
system. For example, a network volume’s
modification dates can change.
26 bTrshOffLine Set this bit to indicate that this volume does not
support an offline state. The PBOffLine function
is not supported by this volume. If the Finder
finds this volume offline, it is zoomed to the Trash
and unmounted.
25 bNoSwitchTo Obsolete. The Finder will not switch launch to
any application on this volume.
24–21 Reserved. Set to zero.
20 bNoDeskItems Set this bit to indicate that this volume does not
support objects on the desktop.If the volume has a
folder named Desktop Folder in it’s root directory,
it is treated as any other directory.
19 bNoBootBlks Set this bit to indicate that this volume is not a
startup volume. The Startup menu item is
disabled. Boot blocks are not copied during copy
operations.
18 bAccessCntl Set this bit to indicate that this volume supports
AppleTalk AFP access-control interfaces. The
PBHGetLoginInfo, PBHGetDirAccess,
PBHSetDirAccess, PBHMapID, and
PBHMapName functions are supported. Special
folder icons are used. The Access Privileges
(System 6) or Sharing (System 7) menu item is
enabled for disk and folder items. The ioACUser
field returned by PBGetCatInfo for folders is
assumed to be valid. Note: volumes with
bAccessCntl and vMServerAdr=0 cannot be
unmounted by the Finder and volumes with
bAccessCntl cannot be renamed.
17 bNoSysDir This volume doesn’t support a system directory.
Do not switch launch to this volume. The system
directory location is not stored in ioVFndrInfo.
16 bHasExtFSVol The bit name isn’t accurate. What this bit says is
that the Disk Initialization Manager is not
supported by this volume’s file system. The
Finder disables Erase Disk item when this bit is
set.
15 bHasOpenDeny This volume supports the PBHOpenDeny and
PBHOpenRFDeny functions.
14 bHasCopyFile This volume supports the PBHCopyFile function,
which is used in copy and duplicate operations if
both source and destination volumes have the
same server address in vMServerAdr.
13 bHasMoveRename This volume supports the PBHMoveRename
function.
12 bHasDesktopMgr This volume supports the Desktop Manager
functions (described in the chapter “Desktop
Manager” in Inside Macintosh: More Macintosh
Toolbox).
11 bHasShortName This volume supports AFP short names with the
GetXCatInfo select code ($3A). Once again, the
bit name isn’t really accurate.
10 bHasFolderLock This volume supports PBHSetFLock and
PBHRstFLock on folders. A locked folder cannot
be deleted or renamed.
9 bHasPersonalAccessPrivileges This volume has local file sharing enabled.
8 bHasUserGroupList The user and group list of the local file server
returned by the PBGetUGEntry function are valid
for this volume.
7 bHasCatSearch This volume supports the PBCatSearch function.
6 bHasFileIDs This volume supports the file ID reference
functions, including the PBExchangeFiles
function.
5 bHasBtreeMgr Reserved for internal Apple use.
4 bHasBlankAccessPrivileges This volume supports inherited AFP access
privileges for folders.
3–0 Reserved. Set them to zero.
Q: Can I write a native Power PC foreign file system with the File System Manager?
A: We do not recommend writing File System Manager-based foreign file systems in native Power PC code because there would be a minimum of two mixed mode switches per file system request you handle (you’ll be called from emulated 68K code). Complex file system requests that cause multiple driver requests could cause many more mixed mode switches. If you think of a place where native code would really help the performance of your file system, you’d be best off putting just that code in a Power PC accelerated code resource and calling it from your foreign file system (which would still be mostly in 68K code) only when you need it.
( d ˇ ˇˇˇˇ d
d , Times
. ° d ONLN d s ` ã≠ +`Ö Guide to the File System Manager
0 ° d ONLN d ! a» ëÓ ( Ö»
° d ONLN d " }Ó àı )&®
° d ONLN d $ï `° ò (û ` Version 1.2 ° d ONLN d 0≠ `π ∫ *September 6, 1994 ˇ d ˇ ˇˇˇˇ d
* 5in a retrieval system, or transmitted, in any form or ° d ONLN d µ ´ H ∂ ⁄ * %by any means, mechanical, electronic, ° d ONLN d € ∑ H ¬ * 4photocopying, recording, or otherwise, without prior ° d ONLN d √ H Œ * 2written permission of Apple Computer, Inc. Printed ° d ONLN dC œ H ⁄ ¿ * in the United States of America. ° d ONLN dd Á H Ú *1No licenses, express or implied, are granted with ° d ONLN dñ Û H ˛ * 2respect to any of the technology described in this ° d ONLN d… ˇ H
* 4book. Apple retains all intellectual property rights ° d ONLN d˛ H ˛ * 0associated with the technology described in this ° d ONLN d/ H" * 1book. This book is intended to assist application ° d ONLN da# H. * 1developers to develop applications only for Apple ° d ONLN dì/ H: ù * Macintosh computers. ° d ONLN d› Á7 Úˇ ( Ô71Even though Apple has reviewed this manual, APPLE ° d ONLN d Û7 ˛Û * $MAKES NO WARRANTY OR REPRESENTATION, ° d ONLN d4 ˇ7
˛ * *EITHER EXPRESS OR IMPLIED, WITH RESPECT TO ° d ONLN d_ 7‚ * #THIS MANUAL, ITS QUALITY, ACCURACY, ° d ONLN dÉ7"Ÿ * !MERCHANTABILITY, OR FITNESS FOR A ° d ONLN d•#7.Á * %PARTICULAR PURPOSE. AS A RESULT, THIS ° d ONLN dÀ/7:› * $MANUAL IS SOLD “AS IS,” AND YOU, THE ° d ONLN d;7F˜ * 'PURCHASER, ARE ASSUMING THE ENTIRE RISK ° d ONLN dG7RŒ * AS TO ITS QUALITY AND ACCURACY. ° d ONLN d®G HR (O H-Every effort has been made to ensure that the ° d ONLN d÷S H^ * 4information in this manual is accurate. Apple is not ° d ONLN d _ Hj Á * ,responsible for printing or clerical errors. ° d ONLN d8_7j )Ô,IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, ° d ONLN dek7v– * !INDIRECT, SPECIAL, INCIDENTAL, OR ° d ONLN dáw7Çı * $CONSEQUENTIAL DAMAGES RESULTING FROM ° d ONLN d¨É7é˛ * (ANY DEFECT OR INACCURACY IN THIS MANUAL, ° d ONLN d’è7öˆ * 3even if advised of the possibility of such damages. ° d ONLN d8w HÇ ö ( HApple Computer, Inc. ° d ONLN dMÉ Hé Ç * 1 Infinite Loop ° d ONLN d]è Hö ö * Cupertino, CA 95014 ° d ONLN dqõ H¶ Ä * 408-996-1010 ° d ONLN d ß7≤Í +Ô #THE WARRANTY AND REMEDIES SET FORTH ° d ONLN d -≥7æÎ * &ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL ° d ONLN d Tø7 ‚ * #OTHERS, ORAL OR WRITTEN, EXPRESS OR ° d ONLN d xÀ7÷Ú * /IMPLIED. No Apple dealer, agent, or employee is ° d ONLN d ®◊7‚˘ * 2authorized to make any modification, extension, or ° d ONLN d €„7Óó * addition to this warranty. ° d ONLN d~≥ Hæ Í (ª H'Apple, the Apple logo, APDA, AppleLink, ° d ONLN d¶ø H Ë * 'AppleShare, AppleTalk, A/UX, EtherTalk, ° d ONLN dŒÀ H÷ * /LaserWriter, Macintosh, MPW, PowerBook, ProDOS, ° d ONLN d˛◊ H‚ * /and TokenTalk are trademarks of Apple Computer, ° d ONLN d.„ HÓ Ú * /Inc., registered in the United States and other ° d ONLN d^Ô H˙ n *
countries. ° d ONLN d ˆ˚7˝ +Ô 4Some states do not allow the exclusion or limitation ° d ONLN d
+7Ú * 4of implied warranties or liability for incidental or ° d ONLN d
`7 ı * 1consequential damages, so the above limitation or ° d ONLN d
í 7*ˇ * 3exclusion may not apply to you. This warranty gives ° d ONLN d
Δ+76Ì * 0you specific legal rights, and you may also have ° d ONLN d
˜77BŸ * ,other rights which vary from state to state. ° d ONLN di H ˝ ( H,Apple Desktop Bus, Apple SuperDrive, Balloon ° d ONLN dñ H * 2Help, Finder, ResEdit, Macintosh Quadra, PowerBook ° d ONLN d… H* * 2Duo, Power Macintosh, System 7, and QuickDraw, are ° d ONLN d¸+ H6 œ * "trademarks of Apple Computer, Inc. ° d ONLN d C HN ˘ *.Motorola is a registered trademark of Motorola ° d ONLN dNO HZ z * Corporation. ° d ONLN d[g Hr *0UNIX is a trademark of UNIX System Laboratories, ° d ONLN dås H~ W * Inc. ° d ONLN dëã Hñ *1Simultaneously published in the United States and ° d ONLN d√ó H¢ f * Canada. ˇ ‰ d ˇ ˇˇˇˇ d
d , Helvetica
. ° d ONLN d V ` h k +`d1 ° d ONLN d V Ñ hñ )$THE FILE SYSTEM MANAGER Q ^ Q h ^ h , Times
(Ú
1- )
1 ˇ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager , Helvetica
° d ONLN d U H d Ú *-ABOUT THIS CHAPTER N F N g F g
° d ONLN d ~ H ä‰ *'VThis chapter describes foreign file systems and the File System Manager (FSM). It also ° d ONLN d j ä H ñÒ * Zprovides a complete description of all FSM data types, FSM service routines available to a ° d ONLN d ≈ ñ H ¢Æ * Iforeign file system and other programs, and the FSM component interfaces.
° d ONLN d « H ÷; *3ABOUT FOREIGN FILE SYSTEMS ¿ F ¿ Ÿ F Ÿ
° d ONLN d* H ¸ *'[A foreign file system allows Macintosh applications to gain access to non-Macintosh volumes ° d ONLN dÜ ¸ HÎ * Vusing File Manager routines. For example, a Macintosh application can use File Manager ° d ONLN d› H˘ * _routines to read from and write to files on a ProDOS disk if there is a foreign file system for ° d ONLN d= H t * ProDOS. ° d ONLN dE, H8˘ *[In the past, developing a foreign file system required extensive knowledge of the Macintosh ° d ONLN d°8 HD‰ * OFile Manager and how it used both documented and undocumented low-memory global ° d ONLN dÒD HP· * Wvariables and data structures. To solve this problem, Apple has written the File System ° d ONLN dIP H\Õ * QManager. To create a new foreign file system, developers no longer need to access ° d ONLN dõ\ Hh€ * Sundocumented portions of the Macintosh and interface with the Macintosh file system ° d ONLN dÔh HtÌ * [through a 68000 register-based interface. Instead, they provide a foreign file system for a ° d ONLN dKt HÄÔ * Wparticular file system that works with the File System Manager. The File System Manager ° d ONLN d£Ä Håˇ * ]provides a systematic way for one or more foreign file systems to interact with the Macintosh ° d ONLN då Hò& * 0file system using high-level language interface. ° d ONLN d2§ H∞Ì *WThe File System Manager performs low-level tasks common to all foreign file systems. It ° d ONLN dä∞ HºÍ * ]intercepts incoming file system related traps, identifies the foreign file system the request ° d ONLN d˺ H»ˇ * ^should be passed to, and then passes on only those requests requiring action by the particular ° d ONLN dG» H‘ˇ * _foreign file system. To develop a foreign file system, you provide a set of foreign file system ° d ONLN dß‘ H‡fi * Sroutines—described in the following chapters—that the File System Manager can call. ° d ONLN d˚Ï T¯ ≤ + Important Note: ° d ONLN d Ï ≤¯ÿ )^:Even though the File System Manager provides many services ° d ONLN dF¯ T‰ ( TVthat simplify development of foreign file systems, developing a foreign file system is ° d ONLN dù T– * Oboth a difficult and time-consuming process. A minimal foreign file system must ° d ONLN dÌ T ‰ * Timplement over forty Macintosh file system routines while a networked, sharable file ° d ONLN dB T(· * Rsystem will have to implement as many as eighty Macintosh file system routines. To ° d ONLN dï( T4— * Rwrite a foreign file system you must be familiar with the low-level Macintosh file ° d ONLN dË4 T@N * 6system data routines and data structures described in ° d ONLN d 4N@º )˙Inside Macintosh: Files ° d ONLN d 54º@Ë )n and with ° d ONLN d ?@ TL (I T,the material covered in the chapters of the ° d ONLN d k@Lª )Δ Guide to the File System Manager ° d ONLN d ã@ªLø )°.
° d ONLN d çw HÜZ (Ç H ABOUT THE FILE SYSTEM MANAGER p Fp â Fâ
° d ONLN d ´† H¨ˇ *'ZThe File System Manager is the part of the Macintosh Operating System that manages the use ° d ONLN d
¨ H∏ * Zof foreign file systems. The File System Manager provides a general means by which foreign ° d ONLN d
a∏ Hƒ¬ * Sfile systems can be installed, identified, and interfaced to the Operating System . *11- )
2 )& About the File System Manager ˇ d ˇ ˇˇˇˇ d
d , Times
. ( 3¢The File System Manager ° d ONLN d U ` a ( ^ `PThe Operating System services provided by the File System Manager are called FSM ° d ONLN d Q a ` m * Zcomponents and the interface mechanism between an foreign file system and a particular FSM ° d ONLN d ¨ m ` y˝ * Pcomponent is known as a FSM component interface. At this time, two FSM component ° d ONLN d ˝ y ` Öy * ;interface are defined for use under the File System Manager ° d ONLN d9 ë l ù p + • ° d ONLN d; ë y ùÙ )
Uthe Disk Initialization Package Component Interface which allows foreign file systems ° d ONLN dÛ ¡ y Õ} * 8to initialize foreign file system volumes on a Macintosh ° d ONLN d, Ÿ ` Â ( ‚ `ZFor each installed file system, the File System Manager maintains a file system descriptor ° d ONLN dá Â ` Ò * \(FSD). Information in the FSD identifies the file system and describes its interfaces to the ° d ONLN d‰ Ò ` ˝˝ * SFile System Manager and to the FSM component interfaces supplied by the File System ° d ONLN d8 ˝ ` Í * PManager. Installed FSDs are kept in the File System Manager’s private FSD queue. ° d ONLN dâ `! *XA foreign file system’s FSD can be installed, accessed, maintained, and removed with the ° d ONLN d‚! `- * ZFSM service routines. FSM service routines also allow applications to communicate with the ° d ONLN d=- `9Û * UFile System Manager and foreign file systems, and allow disk drivers and foreign file ° d ONLN dì9 `Ec * 3systems to communicate with the File System Manager ° d ONLN d«Q `] *VFigure 1-1 shows how the Operating System and the File System Manager work together to ° d ONLN d ] `iF * 2allow applications to access foreign file systems. (ÚW About the File System Manager )¥1- )
3 ˇ– d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager † Ç † å
U N˘˚ 0 è Õ ê Œ 8 8 8 ° ñ ° ö
∏ Z ‚ ò , Helvetica . §≠§≠ ° d ONLN dˇˇ +è
Macintosh
,Ä ° d ONLN dˇˇ *
Operating
⁄@ ° d ONLN dˇˇ *System † ó ° ñ ° ö
c ô
⁄¿ ° d ONLN dˇˇ + + File System ⁄ ° d ONLN dˇˇ * Manager † ó ° ñ ° ö ˇ˝ +
®2¥å MÄ ° d ONLN dˇˇ +œúForeign File System † ó ° ñ ° ö
∏: –s 1 ° d ONLN dˇˇ ( ¡OFile Ä ° d ONLN dˇˇ ( ÕCManager † ó ° ñ ° ö %
∏ì –fl ܇ ° d ONLN dˇˇ ( ¡îDisk Initialization
¯` ° d ONLN dˇˇ + Package † ó
U N˘˚ ™U™U™U™U 0 ±( ◊Ñ 0 ±ã ◊Á 0 Y( 0 û O;˙ ° d
MDPL † å ˇˇˇˇˇˇˇˇ q 'à5ê'å5ê5å5à'å q éàúêúåéàéåéêúå "5å Y † ç ° d MDPL
™U™U™U™U 0 V O ê˙ 1 c| Éú ê ¬ ‚4 ¬ ‚. c| Éú @ † Ä @ @ Ä ¡ Ä @ LÄ r ü„¿ å¿ Ä@¿ @ ¿ ¿ ˘¿ á¿ ¿ à P ° ñ ° ö ˇ˝
1 c É0 ê ¬ ‚4 ¬ ‚. c É0 @ † Ä @ @ Ä ¡ Ä @ LÄ r ü„¿ å¿ Ä@¿ @ ¿ ¿ ˘¿ á¿ ¿ à P 1 c § É ƒ ê ¬ ‚4 ¬ ‚. c § É ƒ @ † Ä @ @ Ä ¡ Ä @ LÄ r ü„¿ å¿ Ä@¿ @ ¿ ¿ ˘¿ á¿ ¿ à P ™U™U™U™U 0ö ¬† ° d MDPL 1WYmâ ° ñ ° ö
WYmâ
° d ONLN dˇˇ +ˇÈ File System ˇp ° d ONLN dˇˇ *
Descriptor † ó ° d MDPL
U N˘˚ ™U™U™U™U "Kå - ° ñ ° ö
)É ° d ONLN dˇˇ ( MHFS
p ° d ONLN dˇˇ (,Component Interface † ó ° ñ ° ö
åÊ Ñ‡ ° d ONLN dˇˇ ( òDisk Initialization
ц ° d ONLN dˇˇ (èComponent Interface † ó ° ñ ° ö )
º ä ° d ONLN dˇˇ ( ¿File System Manager
ä ° d ONLN dˇˇ +
Service Calls † ó
U N˘˚ 0 ˙ ¥ ! 0 ˙) Ñ 0 ˙å Á @IKzó ° ñ ° ö ˇ˝
æ ◊
0 ° d ONLN dˇˇ ( « Ÿ Disk Drivers † ó
U N˘˚ 0 ± ≈ ◊! ° d
MDPL † å ˇˇˇˇˇˇˇˇ q ÷ Ô ‰ ˜ ÷ Û ‰ ˜ ‰ Û ‰ Ô ÷ Û q Ï Ô ˙ ˜ ˙ Û Ï Ô Ï Û Ï ˜ ˙ Û " ‰ Û † ç ° d MDPL
™U™U™U™U @I•zÒ ° d
MDPL † å ˇˇˇˇˇˇˇˇ q '‚5Í'Ê5Í5Ê5‚'Ê q ƒ‚“͓ʃ‚ƒÊƒÍ“Ê 5ÊƒÊ † ç ° d MDPL
™U™U™U™U "KÊ - ° ñ ° ö ˇ˝ +
fiåÍÊ ° d ONLN dˇˇ (ÁçForeign File System † ó
U N˘˚ 0–x¯˙ ˇˇˇˇˇˇˇˇ `ú ¸Ø ¥ Z ° d
MDPL † å q ™≤ Æ ≤Æ™Æ "Æ
† ç ° d MDPL
° d
MDPL † å q ‘, ‹ ÿ, ‹, ÿ, ‘ ÿ , ÿ€ ÿ † ç ° d MDPL
`“ ÿÂ Î ¥ Z ° d
MDPL † å q ‡lËz‰zËl‰l‡l‰z ‰ ·‰l † ç ° d MDPL
° d MDPL 1W≥m„ ° ñ ° ö
W≥m„
° d ONLN dˇˇ (_¥ File System ˇp ° d ONLN dˇˇ *
Descriptor † ó ° d MDPL † ç † É
d
. ° d ONLN d R ì ( R Figure 1-1. ° d ONLN d ì˜ )AI Applications using foreign file systems through the File System Manager (Ú H1- )
4 )& About the File System Manager ˇ, d ˇ ˇˇˇˇ d
d , Times
. ( 3¢The File System Manager , Helvetica
° d ONLN d s ` Çn ( ~ ` USING THE FILE SYSTEM MANAGER l ^ l Ö ^ Ö
° d ONLN d ú ` ® » *'This section describes ° d ONLN d 5 ¥ l ¿ p + • ° d ONLN d 7 ¥ y ¿ )
File system descriptors (FSDs) ° d ONLN d V Ã l ÿ p ( ’ l• ° d ONLN d X Ã y ÿ ¯ )
FSM component interfaces ° d ONLN d q ‰ l p ( Ì l• ° d ONLN d s ‰ y Ñ )
8how to determine if the File System Manager is available ° d ONLN d ¨ ¸ l p ( l• ° d ONLN d Æ ¸ yd )
2how foreign file systems are installed and enabled
° d ONLN d · `/ (+ `File System Descriptors / ^/
° d ONLN d ˘< `H *[The File System Manager maintains a file system descriptor (FSD) for each installed foreign ° d ONLN dUH `T
* ^file system. Information in the FSD identifies the file system and describes its interfaces to ° d ONLN d¥T ``¶ * Athe FSM component interfaces supplied by the File System Manager. ° d ONLN dˆl `x *XA foreign file system’s FSD is installed, accessed, maintained, and removed with the FSM ° d ONLN dOx `Ñ * Zservice routines. FSDs are created with InstallFS. A copy of the information in an FSD can ° d ONLN d™Ñ `ê * Tbe obtained with GetFSInfo. Information in an FSD can be modified with SetFSInfo. An ° d ONLN dˇê `ú * TFSD can be removed with RemoveFS. The FSM service routines use the data type FSDRec. ,
Courier
° d ONLN dT± lΩ Δ + !struct FSDRec { ° d ONLN ddΩ ä… ÿ +
struct FSDRec ° d ONLN drΩ Á… )] *fsdLink; ° d ONLN d|Ωn…‘ )á/* ptr to next */ ° d ONLN dé… ä’ ® (“ äshort ° d ONLN dî… Á’# )]
fsdLength; ° d ONLN dü…n’˛ )á/* length of this FSD in ° d ONLN dΩ’Ä·∞ + bytes */ ° d ONLN dΔ· äÌ ® (Í äshort ° d ONLN d÷ ÁÌ) )] fsdVersion; ° d ONLN dÿ·nÌÊ )á/* version number */ ° d ONLN dÌÌ ä˘ ® (ˆ äshort ° d ONLN dÛÌ Á˘A )]fileSystemFSID; ° d ONLN dÌn˘Ê )á/* file system id */ ° d ONLN d˘ ä ® ( äStr31 ° d ONLN d ˘ ÁA )]fileSystemName; ° d ONLN d.˘nÚ )á/* file system name */ ° d ONLN dE ä Æ ( äFSSpec ° d ONLN dL ÁA )]fileSystemSpec; ° d ONLN d\n˛ )á/* foreign file system's ° d ONLN dzÄ ∂ + FSSpec */ ° d ONLN dÑ ä) ú (& äPtr ° d ONLN dà Á)e )]fileSystemGlobalsPtr; ° d ONLN dû n)Ï )á/* ptr to file system ° d ONLN dπ)Ä5º +
globals */ ° d ONLN dƒ5 äA Δ (> ä
FSDCommUPP ° d ONLN dœ5 ÁAY )]fileSystemCommProc; ° d ONLN d„5nA
)á/* communication proc with ° d ONLN dAÄMº +
the FFS */ ° d ONLN dM äY ¢ (V älong ° d ONLN dM ÁY# )]
reserved3; ° d ONLN d MnY )á/* reserved, must be 0 */ ° d ONLN d8Y äe ¢ (b älong ° d ONLN d=Y Áe# )]
reserved2; ° d ONLN dHYne )á/* reserved, must be 0 */ ° d ONLN dbe äq ¢ (n älong ° d ONLN dge Áq# )]
reserved1; ° d ONLN drenq )á/* reserved, must be 0 */ ° d ONLN dåq ä} ∫ (z äHFSCIRec ° d ONLN dïq Á} )] fsdHFSCI; ° d ONLN düqn}Œ )á/* HFS component ° d ONLN dµ}Äâ» + interface */ ° d ONLN d¬â äï ¥ (í äDICIRec ° d ONLN d â Áï )]fsdDICI; ° d ONLN d”ânïÚ )á/* Disk Initialization ° d ONLN dÔïÄ° + component interface */ ° d ONLN d° ä≠ ñ (™ ä}; ° d ONLN d ≠ äπ8 * typedef struct FSDRec FSDRec; ° d ONLN d'π ä≈& * typedef FSDRec *FSDRecPtr;
+Õ0 Using the File System Manager )¥1- )
5 ˇÃ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d U H a Æ *+Field descriptions ° d ONLN d o H { m *fsdLink ° d ONLN d o ∏ {~ )p,A pointer to the next entry in the FSD list. ° d ONLN d H É H è x ( å H fsdLength ° d ONLN d R É ∏ è] )p#The length of of this FSD in bytes. ° d ONLN d v ó H £ | ( † H
fsdVersion ° d ONLN d Å ó ∏ £‚ )p?The lowest version of the File System Manager this foreign file ° d ONLN d ¡ £ ∏ Øw * )system can support. Currently, this is 1. ° d ONLN d Î ∑ H √ î ( ¿ HfileSystemFSID ° d ONLN d ˙ ∑ ∏ √ )pFThe unique file system ID (FSID) of the foreign file system. See “File ° d ONLN dA √ ∏ œ˘ * >System ID Numbers” on page 1-7 for more information about FSID ° d ONLN dÄ œ ∏ €  * numbers. ° d ONLN dâ „ H Ô ñ ( Ï HfileSystemName ° d ONLN dò „ ∏ Ô„ )pBA Pascal string (Str31) which is used to identify the foreign file ° d ONLN d€ Ô ∏ ˚ˇ * Dsystem. It is not guaranteed to be unique. fileSystemName is used by ° d ONLN d ˚ ∏ˇ * Fthe Disk Initialization Package. The name is displayed in a dialog box ° d ONLN dg ∏Ó * Cthat presents the user a choice of file system formats with which a ° d ONLN d´ ∏ % * disk may be initialized. ° d ONLN dƒ' H3 ë (0 HfileSystemSpec ° d ONLN d”' ∏3Ï )pCAn FSSpec indicating the location of the foreign file system’s file ° d ONLN d3 ∏?ˆ * Ccode file. The File System Manager fills in fileSystemSpec with the ° d ONLN d[? ∏KÔ * Blocation of the current resource file (CurResFile) when the FSD is ° d ONLN dûK ∏W * installed by InstallFS. ° d ONLN d∂_ Hk ≠ (h HfileSystemGlobalsPtr ° d ONLN dÀ_ ∏kÛ )pGA pointer to the foreign file system’s optional global data area. It is ° d ONLN dk ∏w– * <passed to the foreign file system as a parameter for all FSM ° d ONLN dPw ∏ÉÛ * Dcomponent interface requests to the foreign file system. A nil value ° d ONLN dïÉ ∏èÿ * ?indicates no global area was allocated. The global data area is ° d ONLN d’è ∏õØ * 7allocated by the foreign file system installation code. ° d ONLN d
£ HØ ∞ (¨ HfileSystemCommProc ° d ONLN d £ ∏Ø„ )p?A pointer to the foreign file system’s communications function. ° d ONLN d`∑ H√ v (¿ H reserved3 ° d ONLN dj∑ ∏√, )pReserved. Must be zero. ° d ONLN dÇÀ H◊ v (‘ H reserved2 ° d ONLN dåÀ ∏◊, )pReserved. Must be zero. ° d ONLN d§fl HÎ v (Ë H reserved1 ° d ONLN dÆfl ∏Î, )pReserved. Must be zero. ° d ONLN dΔÛ Hˇ z (¸ HfsdHFSCI ° d ONLN dœÛ ∏ˇ˝ )pBThe foreign file system’s HFS component interface record. See “The ° d ONLN dˇ ∏ * AHFS Component Interface Record” in Chapter 2 for more information ° d ONLN dT ∏Ñ * )about the HFS component interface record. ° d ONLN d~ H+ o (( HfsdDICI ° d ONLN dÜ ∏+Ê )pAThe foreign file system’s Disk Initialization component interface ° d ONLN d»+ ∏7˙ * Crecord. See “The Disk Initialization Component Interface Record” in ° d ONLN d 7 ∏C– * <Chapter 4 for more information about the Disk Initialization ° d ONLN dIC ∏O< * component interface record. , Helvetica
° d ONLN deg Hv ı (r HFile System ID Numbers
° d ONLN d|Å Hç˚ *^A file system ID (FSID) number is a unique word-length value that identifies a particular file ° d ONLN d€ç Hô * Zsystem. This number is used by the Macintosh file system and by the File System Manager to ° d ONLN d6ô H•Ò * \identify a particular file system. The FSID value passed to InstallFS is checked by the File ° d ONLN dì• H±Ó * XSystem Manager to insure that a FSD with that FSID is not already installed. The FSID is ° d ONLN dϱ HΩÛ * ^passed as a parameter to all File System Manager service routines. Table 1-1 is a list of file ° d ONLN d KΩ H…: * 1system IDs currently owned by Apple file systems. *,1- )
6 )& Using the File System Manager ˇ2 d ˇ ˇˇˇˇ d
d , Times
. ( 3¢The File System Manager ° d ONLN d U ` a ( ^ `Table
° d ONLN d V a Å )
° d ONLN d U Å a ô )1-1. ° d ONLN d U ® aÄ )'+File System IDs owned by Apple file systems ° d ONLN d 7 l ` x ~ ( u `FSID ° d ONLN d < l ñ x Ÿ )6 File System e ^ e ° d ONLN d H Ñ ` ê ~ ( ç `$0000 ° d ONLN d N Ñ ñ ê )6Macintosh HFS or MFS ° d ONLN d d ú ` ® ~ ( • `$0100 ° d ONLN d j ú ñ ® ˘ )6ProDOS File System ° d ONLN d ~ ¥ ` ¿ ~ ( Ω `$0101 ° d ONLN d Ñ ¥ ñ ¿ )6PowerTalk Mail Enclosures ° d ONLN d ü Ã ` ÿ ~ ( ’ `$4147 ° d ONLN d • Ã ñ ÿé )62ISO 9660 File Access (through Foreign File Access) ° d ONLN d Ÿ ‰ ` ~ ( Ì `$4242 ° d ONLN d fl ‰ ñ ó )65High Sierra File Access (through Foreign File Access) ° d ONLN d ¸ ` Ä ( `$464D ° d ONLN d ¸ ñï )63QuickTake File System (through Foreign File Access) ° d ONLN dQ ` ~ ( `$4953 ° d ONLN dW ñ A )6 Macintosh PC Exchange (MS-DOS) ° d ONLN dw, `8 Ä (5 `$4A48 ° d ONLN d}, ñ8{ )6-Audio CD Access (through Foreign File Access) ° d ONLN d¨D `P Ç (M `$4D4B ° d ONLN d≤D ñPÜ )60Apple Photo Access (through Foreign File Access) ° d ONLN dÂh `t
(q `XFSID values between $0001 and $00FF are reserved for old-style foreign file systems that ° d ONLN d>t `Ä * Zdetermine their FSID’s dynamically (i.e., by searching the drive queue) and cannot be used ° d ONLN dôÄ `å9 * -for File System Manager foreign file systems. ° d ONLN d«ò `§ *VFSID values between $0100 and $7FFF are reserved for the File System Manager and other ° d ONLN d § `∞ä * @foreign file systems that use registered file system ID numbers. ° d ONLN d_º `»Ë *OFSID values $8000 and above are reserved for future use by Apple Computer, Inc. ° d ONLN dØ‘ `‡ *RFSID values fsmIgnoreFSID ($FFFE) and fsmGenericFSID ($FFFF) have special meaning. ° d ONLN d‡ `Ï * ^fsmIgnoreFSID is stored in the partition map on a partitioned disk. It signals the disk driver ° d ONLN daÏ `¯ * _not to install this partition into the drive queue. fsmGenericFSID is stored in the drive queue ° d ONLN d¡¯ ` * Xelement (DrvQEl) by the disk driver to signal an unknown foreign file system volume. The ° d ONLN d ` * _File System Manager will attempt to find a foreign file system that can identify disks with the ° d ONLN dz ` Û * PfsmGenericFSID by calling each foreign file system with the ffsIDVolMountMessage ° d ONLN dÀ `( * Vmessage. This allows disk drivers to support multiple volume formats without having to ° d ONLN d"( `4 · * identify the volume format. ° d ONLN d>@ `L¸ *STo reserve a FSID in the File System Manager range ($0100 through $7FFF), a special ° d ONLN díL `XÍ * Qcreator type must be registered with Apple’s Developer Support Center (AppleLink: ° d ONLN d‰X `d * QDEVSUPPORT). The high word of the creator type must be $0613. The low word of the ° d ONLN d6d `p * _creator type is the FSID to register. For example, to reserve the FSID $0100 for a foreign file ° d ONLN dñp `| * [system, the creator type $06130100 should be registered. The creator type registered for an ° d ONLN dÚ| `à˚ * XFSID can also be used as the creator type of the system extension file that implements a ° d ONLN dKà `î º * foreign file system. ° d ONLN d`† l¨ ß +
Important: ° d ONLN dj† ß¨Í );A File System ID numbers in the File System Manager range were not ° d ONLN d¨¨ l∏¸ (µ lXregistered before 1993. As a result, there are foreign file systems in use that have not ° d ONLN d ∏ lƒ˚ * Tregistered with Apple’s Developer Support Center. If you are the publisher of one of +Î1 Using the File System Manager )¥1- )
7 ˇ
Ó d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d U T a‰ + +Vthose foreign file systems, please register your FSID immediately to help prevent file ° d ONLN d W a T m ≥ * system ID conflicts. , Helvetica
° d ONLN d l Ö H î[ ( ê H#File System Communications Function
° d ONLN d ê ü H ´¯ *TThe communications function pointed to by fileSystemCommProc in an FSDRec is used by ° d ONLN d  ´ H ∑Ô * Wthe File System Manager to communicate with a foreign file system. When the file system ° d ONLN d= ∑ H √˛ * ^communications function is called, it is passed a message and a pointer to a buffer containing ° d ONLN dú √ H œ * [any additional parameters needed to process the message. The currently defined messages are ° d ONLN d¯ œ H € ° * listed in Table 1-2. ° d ONLN d
Á H Û g *Table
° d ONLN d Ë g Û i )
° d ONLN d Á i Û Å )1-2. ° d ONLN d Á ê Ûy )',File System Communications Function Messages ° d ONLN dE ˛ H
x ( HMessage ° d ONLN dM ˛ ÿ
)êPurpose ˜ F ˜ ° d ONLN dU H" ì ( H
ffsNopMessage ° d ONLN dc Δ" à )~0 ° d ONLN de ÿ" )<No operation. The file system communications function should ° d ONLN d¢" ÿ.k * simply return a result of noErr. ° d ONLN dƒ: HF § (C HffsGetIconMessage ° d ONLN d÷: ΔF à )~1 ° d ONLN dÿ: ÿFZ )Return disk icon and mask. ° d ONLN dÙR H^ † ([ HffsIDDiskMessage ° d ONLN dR Δ^ à )~2 ° d ONLN dR ÿ^õ )(Identify the volume about to be mounted. ° d ONLN d1j Hv ñ (s HffsLoadMessage ° d ONLN d@j Δv à )~3 ° d ONLN dBj ÿv˙ );Load the foreign file system’s HFS component interface code ° d ONLN d~v ÿÇ * and data. ° d ONLN dâé Hö ° (ó HffsUnloadMessage ° d ONLN döé Δö à )~4 ° d ONLN dúé ÿöÏ )8Unload the foreign file system’s HFS component interface ° d ONLN d’ö ÿ¶ * code and data. ° d ONLN dÂ≤ Hæ ∫ (ª HffsIDVolMountMessage ° d ONLN d˙≤ Δæ à )~5 ° d ONLN d¸≤ ÿæ≈ )2Identify a VolMountInfo record by its media field. ° d ONLN d0 H÷ ü (” HffsInformMessage ° d ONLN dA Δ÷ à )~6 ° d ONLN dC ÿ÷à )$Foreign file system defined message. ° d ONLN di‚ HÓ– (Î HV The file system communications function is described in detail later in this chapter.
° d ONLN d¿ H √ * Global Data Area
° d ONLN d— H&Û *YUnlike a Macintosh application, a foreign file system possesses no A5 world. Therefore, a ° d ONLN d+& H2˚ * \foreign file system cannot define and use global variables. Instead, the File System Manager ° d ONLN dà2 H>Ù * ^allows a foreign file system to allocate a global data area which is used to store data needed ° d ONLN dÁ> HJ Ì * $globally by the foreign file system. ° d ONLN d V HbÏ *[The global data area must be allocated in the system heap before the foreign file system is ° d ONLN dhb HnÓ * ]installed and the address of the global data area is stored in the foreign file system’s FSD. ° d ONLN dΔn HzÚ * [Every time the File System Manager calls a foreign file system function, the address of the ° d ONLN d"z HÜÚ * ]global data area is passed to the foreign file system as one of the function parameters. This ° d ONLN dÄÜ Híæ * Tallows any part of a foreign file system to access the data in its global data area. *c1- )
8 )& Using the File System Manager ˇÜ d ˇ ˇˇˇˇ d
d , Times
. ( 3¢The File System Manager , Helvetica
° d ONLN d U ` d% ( ` `FSM Component Interfaces d ^ d
° d ONLN d q ` } *QThe File System Manager supplies an interface mechanism known as an FSM component ° d ONLN d k } ` â * Yinterface. An FSM component interface can be any functional interface exported by a given ° d ONLN d ≈ â ` ï * SMacintosh operating system or toolbox component. Each FSM component interface is an ° d ONLN d ï ` ° * Xindependent interface, defined and managed by a particular Macintosh operating system or ° d ONLN dr ° ` ≠ * _toolbox component. This includes the definition of the calls involved, the dispatching of calls ° d ONLN d“ ≠ ` π˙ * Xto the foreign file systems, and the execution environment in which those calls operate. ° d ONLN d+ ≈ ` —ˆ *TAt this time, two FSM component interfaces are defined for use under the File System ° d ONLN dÄ — ` › â * Manager ° d ONLN dà È l ı p + • ° d ONLN dä È y ıÙ )
Nthe HFS Component Interface which allows a foreign file system to process File ° d ONLN dŸ ı y à * Manager requests ° d ONLN dÍ
° d ONLN d_˘ ` *WThe first long word of an FSM component interface record is the FSM component interface ° d ONLN d∑ `˘ * Sdispatch mask (compInterfMask). The bits of the compInterfMask currently have these ° d ONLN d ` ê * meanings: ° d ONLN d5 lA } + $Bit ° d ONLN d5 ñA ∂ )*Name ° d ONLN d 54Ad )ûMeaning ° d ONLN d&M lY Ç (V l0-23 ° d ONLN d,M4Y )»-FSM component interface dependent flags. Each ° d ONLN d]Y4e¯ * +component is free to define these flag bits ° d ONLN dåe4qf *
as needed. ° d ONLN dóq l} à (z l24-29 ° d ONLN dûq4} )»+Reserved for the File System Manager’s use. ° d ONLN d } lâ x (Ü l30 ° d ONLN dÕ} ñâ )*fsmComponentBusyBit ° d ONLN d·}4â )û2If set, the FSM component interface is busy (i.e., ° d ONLN d â4ï * 2one or more requests are outstanding). This bit is ° d ONLN d Mï4° * 0maintained by the component and used by the File ° d ONLN d Å°4≠ı * (System Manager to control the use of the ° d ONLN d ≠≠4π * .SetFSInfo File System Manager service routine. +#< Using the File System Manager )¥1- )
9 ˇ
t d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d U T a ` + +31 ° d ONLN d U ~ a ı )*fsmComponentEnableBit ° d ONLN d U aÌ )û+If set, the component may begin dispatching ° d ONLN d H a m * 5requests to the foreign file system. The foreign file ° d ONLN d Å m y * -system should set this bit with the SetFSInfo ° d ONLN d ≤ y Öı * .File System Manager service routine once it is ° d ONLN d ‰ Ö ëî * ready to receive requests. , Helvetica
° d ONLN d ˇ £ H ≤ú ( Æ H+FSM Component Interface Processing Function
° d ONLN d+ Ω H …˜ *WThe second long word of an FSM component interface record is a pointer (compInterfProc) ° d ONLN dÉ … H ’Á * Yto the foreign file system code responsible for processing redirected operating system or ° d ONLN d› ’ H ·Ì * Ztoolbox requests. Which operating system or toolbox requests are redirected is part of the ° d ONLN d8 · H Ì ˆ * #FSM component interface definition.
° d ONLN då H%Á *VIn order to insure some degree of uniformity across FSM component interfaces, the File ° d ONLN d„% H1— * ISystem Manager imposes some common conventions for use by components when ° d ONLN d-1 H=à * Ddispatching requests to a foreign file system. Those conventions are ° d ONLN drI TU X + • ° d ONLN dtI aU¸ )
VThe global pointer (fileSystemGlobalsPtr) from the FSD record is passed to the foreign ° d ONLN dÀU aa * Wfile system on all requests. The global pointer is needed to locate context information ° d ONLN d#a amf * 9associated with the operation of the foreign file system. ° d ONLN d]y TÖ X (Ç T• ° d ONLN d_y aÖ¯ )
¡ aÕ= * ,component interface parameters by SetFSInfo.
° d ONLN d7Â HÙO ( H#Ensuring the File System Manager is ° d ONLN d[Û H ä * Available Få
° d ONLN de H˘ *ZYou must ensure the File System Manager is available on the user’s computer before calling ° d ONLN d¿ H' * [the File System Manager. You can determine is the File System Manager is available by using ° d ONLN d ' H3fl * Wthe Gestalt function. The Gestalt selector is gestaltFSAttr. The File System Manager is ° d ONLN dt3 H?s * Cavailable if the Gestalt function returns a result of noErr and the ° d ONLN d∏? HKÄ * AgestaltHasFileSystemManager bit is set in the response parameter. ° d ONLN d˙W Hc˚ *\In addition, you must ensure the File System Manager is version 1.2. Earlier versions of the ° d ONLN dWc Ho÷ * TFile System Manager do not implement all of the interfaces described in this manual. *Ü1- )
10 )& Using the File System Manager ˇ ¶ d ˇ ˇˇˇˇ d
d , Times
. ( 3¢The File System Manager ° d ONLN d a ` mÚ ( j `VListing 1-1 illustrates how you use Gestalt to determine if the File System Manager is ° d ONLN d W m ` y∑ * Javailable and ensure that the File System Manager is version 1.2 or later. ° d ONLN d ¢ Ö à ë Ã +( Listing 1-1. ° d ONLN d Æ Ö Ã ëÚ )D= Testing for the required version of the File System Manager ,
Courier
° d ONLN d Ï ö ` ¶ Ñ ( £ `static ° d ONLN d Û ö ñ ¶ ¿ )6Boolean ° d ONLN d ˚ ö à ¶D )6HasRequiredFSM(void) ° d ONLN d ¶ ` ≤ f ( Ø `{ ° d ONLN d ≤ r æ ä + long ° d ONLN d ≤ ñ æ à )$ response; ° d ONLN d# æ r ú ( « rBoolean ° d ONLN d+ æ ® “ )6result; ° d ONLN d6 ÷ r ‚ à ( fl rresult = false; ° d ONLN dG ‚ r Ó™ * 4/* Make sure the File System Manager is installed */ ° d ONLN d} Ó r ˙ò * 1if ( Gestalt(gestaltFSAttr, &response) == noErr ) ° d ONLN d∞ ˙ r x * { ° d ONLN d¥ ÑÏ + <if ( (response & (1L << gestaltHasFileSystemManager)) != 0 ) ° d ONLN dÛ Ñ ä * { ° d ONLN d¯ ñ*Œ + 4/* We require File System Manager 1.1 features so */ ° d ONLN d0* ñ6P * /* check the version of FSM. */ ° d ONLN dS6 ñB‘ * 5if ( Gestalt(gestaltFSMVersion, &response) == noErr ) ° d ONLN dåB ñN ú * { ° d ONLN díN ®Z¯ + 8/* Make sure we have File System Manager 1.2 or later */ ° d ONLN dœZ ®fí * 'if ( (unsigned long)response >= 0x0120) ° d ONLN d¸f ∫r + result = true; ° d ONLN dr ñ~ ú ({ ñ} ° d ONLN d~ Ñä ä (á Ñ} ° d ONLN dä rñ x (ì r} ° d ONLN dñ r¢ fi * return ( result ); ° d ONLN d+¢ `Æ f (´ `} , Helvetica
° d ONLN d-Õ `‹l *-&Installing and Enabling a Foreign File ° d ONLN dT€ `Í ï *System Í ^ͧ
° d ONLN d[˜ ` *^Installation of foreign file systems will usually be accomplished by a system extension (INIT) ° d ONLN d∫ ` * \file’s code at startup time. The mechanism that executes a system extension (commonly called ° d ONLN d `Í * Pthe INIT 31 mechanism) is described in Chapter 29 “The System Resource File” in ° d ONLN dgÍ (ÍInside ° d ONLN dn `' » ($ `Macintosh Volume IV ° d ONLN dÅ »'Ç )h', in Chapter 19 “The Start Manager” in ° d ONLN d®Ç' )∫Inside Macintosh Volume V ° d ONLN d¡'
)Ñ, ° d ONLN d√' `3 Ä (0 `and in ° d ONLN d ' Ä3S ) ,Inside Macintosh: Operating System Utilities ° d ONLN dˆ'S3 )”%. The INIT 31 mechanism will load and ° d ONLN d 3 `?˙ (< `[execute the foreign file system installation code in an 'INIT' resource in the foreign file ° d ONLN dx? `K ó * system file. ° d ONLN dÖW `c *_The installation can also be done from within an application if precautions are taken to ensure ° d ONLN dÂc `o * cthe foreign file system is installed in the system heap, or if installed in the application’s heap, ° d ONLN dIo `{ * Xthat all volume are unmounted and the foreign file system removed before the application ° d ONLN d¢{ `á { * quits. +˜n Using the File System Manager )Æ1- )
° d ONLN d s ` DZ ( ~ `$FILE SYSTEM MANAGER SERVICE ROUTINES l ^ l Ö ^ Ö
° d ONLN d % ú ` ®
*'XSix FSM service routines are provided by the File System Manager. These service routines ° d ONLN d ~ ® ` ¥ˆ * Wlet you install, access, maintain and remove the information in the FSDs, send the File ° d ONLN d ÷ ¥ ` ¿ * YSystem Manager messages, and send file system specific messages to a foreign file system. ° d ONLN d0 ¿ ` ÃG * 1The FSM service routines are listed in Table 1-3. ° d ONLN db ÿ ` ‰ *Table
(¨ `UAll of the FSM service routines execute synchronously. GetFSInfo and SetFSInfo may be ° d ONLN d°Ø `ª * Ycalled at any time. InstallFS, RemoveFS, and InformFSM cannot be called by code executing ° d ONLN d˚ª `« * Nat interrupt time — they may make Memory Manager requests that move memory, or ° d ONLN dJ« `” * Ysynchronous operating system requests. Note that the File System Manager service routines ° d ONLN d§” `fl˚ * Xare not Macintosh file system routines and are not controlled by the file system queuing ° d ONLN d˝fl `Î ô *
mechanism.
° d ONLN d ` † *& InstallFS ^§
° d ONLN d `+» *MUse the InstallFS function to add a new file system descriptor to the system. ,
Courier
° d ONLN d`8 `D\ **pascal short InstallFS (FSDRecPtr fsdPtr);
° d ONLN dãO `[ } *fsdPtr ° d ONLN díO Ã[ )lBContains a pointer to an FSDRec initialized with the data you want ° d ONLN d’[ Ãg * Hcopied to the file system descriptor InstallFS creates in the FSD queue. +ié$File System Manager Service Routines )–1- )
13 ˇˆ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d i T u ü + ?
fsdPtr record , Symbol ° d ONLN d u T Ü ` *Æ ° d ONLN d y g Ö ó ) fsdLength ° d ONLN d y ÿ Ö )qshort ° d ONLN d y; Öÿ )c Contains the size of the FSDRec. ° d ONLN d E Ü; í‚ *
Should always be sizeof(FSDRec). ° d ONLN d f í T £ ` ( ü TÆ ° d ONLN d h ñ g ¢ õ )
fsdVersion ° d ONLN d s ñ ÿ ¢ )qshort ° d ONLN d y ñ; ¢Í )c#Contains the minimum version of the ° d ONLN d ° £; ØÍ *
%File System Manager this foreign file ° d ONLN d À Ø; ª‰ * $system will work with. For the first ° d ONLN d Ù ª; «≥ * release, use fsdVersion1. ° d ONLN d « T ÿ ` ( ‘ TÆ ° d ONLN d À g ◊ ≥ )fileSystemFSID ° d ONLN d À ÿ ◊ )qshort ° d ONLN d% À; ◊fi )c"Contains the unique file system ID ° d ONLN dL ÿ; ‰⁄ *
"(FSID) of the foreign file system. ° d ONLN do ‰ T ı ` ( Ò TÆ ° d ONLN dq Ë g Ù µ )fileSystemName ° d ONLN dÄ Ë ÿ Ù Ú )qStr31 ° d ONLN dÜ Ë; Ù )c&Conatins a Pascal string which is used ° d ONLN d± ı;Ê *
&to identify the foreign file system by ° d ONLN d‹;
X * name. ° d ONLN d‚
T ` ( TÆ ° d ONLN d‰ g à )fileSystemGlobalsPtr ° d ONLN d˘ ÿ Ê )qPtr ° d ONLN d˝;  )c&Contains a pointer to the foreign file ° d ONLN d( ;*fi *
#system’s optional global data area. ° d ONLN dL* T; ` (7 TÆ ° d ONLN dN. g: œ )fileSystemCommProc ° d ONLN da. ÿ:% )q
FSDCommUPP ° d ONLN dl.;:Â )c&Contains a pointer to the foreign file ° d ONLN dó;;G„ *
!system’s communications function. ° d ONLN dπG TX ` (T TÆ ° d ONLN dªK gW ï ) reserved3 ° d ONLN d≈K ÿW Ì )qlong ° d ONLN d K;Wπ )cReserved field. Must be 0. ° d ONLN dÂX Ti ` (e TÆ ° d ONLN dÁ\ gh ï ) reserved2 ° d ONLN dÒ\ ÿh Ì )qlong ° d ONLN dˆ\;hπ )cReserved field. Must be 0. ° d ONLN di Tz ` (v TÆ ° d ONLN dm gy ï ) reserved1 ° d ONLN d m ÿy Ì )qlong ° d ONLN d"m;yπ )cReserved field. Must be 0. ° d ONLN d=z Tã ` (á TÆ ° d ONLN d?~ gä ô )fsdHFSCI ° d ONLN dH~ ÿä
)qHFSCIRec ° d ONLN dQ~;äÙ )c&Contains the foreign file system’s HFS ° d ONLN d|ã;óø *
component interface record. ° d ONLN dòó T® ` (§ TÆ ° d ONLN döõ gß é )fsdDICI ° d ONLN d¢õ ÿß )qDICIRec ° d ONLN d™õ;ßÛ )c'Contains the foreign file system’s Disk ° d ONLN d÷®;¥◊ *
"Initialization component interface ° d ONLN d˝¥;¿] * record. ° d ONLN d– H‹ ≤ (Ÿ HThe InstallFS function ° d ONLN d Ë TÙ X + • ° d ONLN d Ë aÙ& )
)validates the FSDRec pointed to by fsdptr ° d ONLN dH T X ( T• ° d ONLN dJ a )
&allocates a new file system descriptor ° d ONLN dq T$ X (! T• ° d ONLN ds a$∑ )
Hcopies the FSDRec pointed to by fsdptr to the new file system descriptor ° d ONLN dº0 T< X (9 T• ° d ONLN dæ0 a<ÿ )
Lclears the fsdHFSCI and fsdDICI compInterfMask fields in the new file system ° d ONLN d < aH ê *
descriptor ° d ONLN dT T` X (] T• ° d ONLN dT a`ÿ )
Sinitializes fileSystemSpec in the new file system descriptor to the location of the ° d ONLN dl` al * &resource file referenced by CurResFile ° d ONLN dìx TÑ X (Å T• ° d ONLN dïx aÑÃ )
Jadds the new file system descriptor to the File System Manager’s FSD queue ° d ONLN d‡ê Hú¯ (ô HWNote that the FSDRec passed by fsdptr is only copied by InstallFS. The FSDRec passed by ° d ONLN d8ú H®ï * Cfsdptr does not become part of the File System Manager’s FSD queue. *M1- )
14 )&$File System Manager Service Routines ˇ h d ˇ ˇˇˇˇ d
d , Times
. ( 3¢The File System Manager ° d ONLN d i l u ® ( r l Result codes ° d ONLN d
u Å ö + noErr ° d ONLN d u Å )è0 ° d ONLN d u3 Å\ )%No error ° d ONLN d Å ç ‰ ( ä fsmBadFFSNameErr ° d ONLN d / Å ˛ ç )-433 ° d ONLN d 4 Å3 ç˜ )5(length of fsdPtr->fileSystemName is 0 or ° d ONLN d ` ç3 ôy * greater than 31 ° d ONLN d p ô • € ( ¢ fsmBadFSDLenErr ° d ONLN d Ä ô ˛ • )-434 ° d ONLN d Ö ô3 •‰ )5'The file system descriptor is too large ° d ONLN d ∞ •3 ±‘ * "(fsdPtr->fsdLength is greater than ° d ONLN d ÷ ±3 ΩÉ * sizeof(FSDRec)) ° d ONLN d Ê Ω … Ê ( Δ fsmDuplicateFSIDErr ° d ONLN d ˙ Ω ˛ … )-435 ° d ONLN d ˇ Ω3 … )5*An FSD with fsdPtr->fileSystemFSID already ° d ONLN d- …3 ’í * exists in FSD queue ° d ONLN dA ’ · Ó ( fi fsmBadFSDVersionErr ° d ONLN dU ’ ˛ · )-436 ° d ONLN dZ ’3 ·Â )5&fsdPtr->fsdVersion is greater than the ° d ONLN dÑ ·3 ÌΩ * File System Manager version ° d ONLN d† Ì ˘ ∏ ( ˆ
memFullErr ° d ONLN d´ Ì ˛ ˘ )-108 ° d ONLN d∞ Ì3 ˘ )5+The new file system descriptor could not be ° d ONLN dfl ˘3\ * allocated , Helvetica
° d ONLN dÈ' `6 Ø (2 `RemoveFS 6 ^6§
° d ONLN dÚC `OÊ *OUse the RemoveFS function to remove file system descriptor from the File System ° d ONLN dBO `[ Œ * Manager’s FSD queue. ,
Courier
° d ONLN dWh `t2 *#pascal short RemoveFS (short fsid);
noErr ° d ONLN dG˙ )è0 ° d ONLN dI˙3\ )%No error ° d ONLN dR Œ (
fsmBusyFFSErr ° d ONLN d` ˛ )-432 ° d ONLN de3Ò )5'A volume with the fsid is mounted or an ° d ONLN dê3 ◊ * FSM component interfaces is busy ° d ONLN d± * Ê (' fsmFFSNotFoundErr ° d ONLN d√ ˛* )-431 ° d ONLN d» 3* )5,The file system descriptor with fsid was not ° d ONLN d¯*36§ * found in the FSD queue
° d ONLN dX `g ™ (c ` GetFSInfo g ^g§
° d ONLN dt `į *WUse the GetFSInfo function to get a copy of a file system descriptor in the File System ° d ONLN dqÄ `å Œ * Manager’s FSD queue.
° d ONLN dÜô `•Ï *Bpascal short GetFSInfo (short selector, short key, short *bufSize, ° d ONLN d–• ˜±c +ó FSDRecPtr fsdptr);
+>D$File System Manager Service Routines )–1- )
15 ˇÚ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d W H c l *-selector ° d ONLN d W ¥ c‘ )l>Contains the method used to select the file system descriptor. ° d ONLN d H k H w Y ( t Hkey ° d ONLN d L k ¥ w¬ )l;Contains the key used to select the file system descriptor. ° d ONLN d à H ã l ( à HbufSize ° d ONLN d ê ¥ ãÌ )lFContains a pointer to a short. On input, the field referred to by this ° d ONLN d ◊ ã ¥ ó„ * Bparameter contains the size of the buffer pointed to by fsdPtr; on ° d ONLN d ó ¥ £ * Eoutput, GetFSInfo places the number of bytes actually copied from the ° d ONLN d` £ ¥ ØÎ * Gfile system descriptor to the buffer into the field referred to by this ° d ONLN d® Ø ¥ ª Ê *
parameter. ° d ONLN d≥ √ H œ e ( à HfsdPtr ° d ONLN d∫ √ ¥ œ„ )l>Contains pointer to a FSDRec. GetFSInfo copies the file system ° d ONLN d˘ œ ¥ €¿ * 9descriptor into the FSDRec referred to by this parameter. ° d ONLN d3 Ì H ˘Ò ( ˆ HXThe GetFSInfo function returns a copy of an file system descriptor in the FSD queue. The ° d ONLN då ˘ Hµ * OGetFSInfo function selects the file system descriptor according to these rules: ° d ONLN d‹ T X + • ° d ONLN dfi a ‡ )
PIf selector is fsmGetFSInfoByIndex, GetFSInfo returns returns a copy of the file ° d ONLN d/ a) * Vsystem descriptor whose position in the FSD queue is specified by the key parameter. A ° d ONLN dÜ) a5√ * Mkey of 0 returns a copy of the first file system descriptor in the FSD queue. ° d ONLN d‘A TM X (J T• ° d ONLN d÷A aMfl )
OIf selector is fsmGetFSInfoByFSID, GetFSInfo returns returns a copy of the file ° d ONLN d&M aY¡ * Isystem descriptor whose File System ID is specified by the key parameter. ° d ONLN dpe Tq X (n T• ° d ONLN dre aqÓ )
QIf selector is fsmGetFSInfoByRefNum, GetFSInfo returns returns a copy of the file ° d ONLN dƒq a}› * Psystem descriptor using the volume or file reference number specified by the key ° d ONLN d} a⡠* Uparameter. The key parameter must be a valid file or volume reference number and must ° d ONLN dkâ aï” * Obe a file or volume owned by a foreign file system installed by the File System ° d ONLN dªï a° é * Manager. ° d ONLN dƒµ T¡ ê (æ T Result codes ° d ONLN d—¡ gÕ Ç + noErr ° d ONLN d◊¡ ˆÕ ¸ )è0 ° d ONLN dŸ¡ÕD )%No error ° d ONLN d‚Õ gŸ ñ (÷ grfNumErr ° d ONLN dÎÕ ÏŸ ¸ )Ö-51 ° d ONLN dÔÕŸÍ )/*The key was an invalid reference number or ° d ONLN d ŸÂfi * )referenced a volume not controlled by the ° d ONLN dJÂÒ * File System Manager ° d ONLN d^Ò g˝ Œ (˙ gfsmFFSNotFoundErr ° d ONLN dpÒ Ê˝ ¸ )-431 ° d ONLN duÒ˝˜ )5/The file system descriptor with the FSID, or at ° d ONLN d®˝ ◊ * (the specified index was not found in the ° d ONLN d‘ P * FSD queue , Helvetica
° d ONLN dfi7 HF ê (B H SetFSInfo F FFå
° d ONLN dËS H_˜ *ZUse the SetFSInfo function to change a file system descriptor in the File System Manager’s ° d ONLN dC_ Hk Å *
FSD queue. ,
Courier
° d ONLN dNx HÑÊ *Epascal short SetFSInfo (short fsid, short bufSize, FSDRecPtr fsdptr);
° d ONLN dîè Hõ Z *fsid ° d ONLN dôè ¥õ˘ )lEContains the unique file system ID (FSID) of the foreign file system. ° d ONLN dfl£ HØ l (¨ HbufSize ° d ONLN dÁ£ ¥Øß )l5Contains the size of the buffer pointed to by fsdPtr. ° d ONLN d ∑ H√ e (¿ HfsdPtr ° d ONLN d$∑ ¥√Ú )lCContains a pointer to an FSDRec containing the data to be copied to ° d ONLN dh√ ¥œ. * the file system descriptor. (Ú H1- )
16 )&$File System Manager Service Routines ˇ ¯ d ˇ ˇˇˇˇ d
d , Times
. ( 3¢The File System Manager ° d ONLN d U ` a ( ^ `]SetFSInfo changes the file system descriptor specified by the fsid parameter. This routine is ° d ONLN d ^ a ` m * [normally used following InstallFS to enable the foreign file system’s component interfaces. ° d ONLN d ∫ m ` y * \bufSize bytes are copied to the file system descriptor from the buffer pointed to by fsdPtr. ° d ONLN d y ` Ö * VThe fsdLink, fsdLength, fsdVersion, fileSystemFSID, fileSystemName, and fileSystemSpec ° d ONLN dn Ö ` ëñ * Cfields in the file system descriptor are not modified by SetFSInfo. ° d ONLN d≤ • l ± ® + Result codes ° d ONLN dø ± Ω ö + noErr ° d ONLN d≈ ± Ω )è0 ° d ONLN d« ±3 Ω\ )%No error ° d ONLN d– Ω … Ê ( Δ fsmFFSNotFoundErr ° d ONLN d‚ Ω ˛ … )-431 ° d ONLN dÁ Ω3 … )5(The file system descriptor with fsid was ° d ONLN d …3 ’∂ * not found in the FSD queue ° d ONLN d. ’ · Œ ( fi
fsmBusyFFSErr ° d ONLN d< ’ ˛ · )-432 ° d ONLN dA ’3 ·¸ )5(An FSM component interfaces is busy; the ° d ONLN dm ·3 Ìı * )file system descriptor cannot be modified ° d ONLN dó Ì ˘ € ( ˆ fsmBadFSDLenErr ° d ONLN dß Ì ˛ ˘ )-434 ° d ONLN d¨ Ì3 ˘ )5+The number of bytes specified by bufSize is ° d ONLN d€ ˘3Á * (larger than the file system descriptor’s ° d ONLN d3{ * fsdLength field ° d ONLN d Û ( fsmNoAlternateStackErr ° d ONLN d. ˛ )-437 ° d ONLN d33 )5/An attempt was made to enable the file system’s ° d ONLN de 3) * .HFS component interface but no alternate stack ° d ONLN dó)35‹ * was provided in fsdPtr->fsdHFSCI , Helvetica
° d ONLN d∏W `f ∞ (b ` InformFSM f ^f§
° d ONLN d¬s `À *GUse the InformFSM function to communicate with the File System Manager. ,
Courier
° d ONLN d
å `ò» *<pascal short InformFSM (short theMessage, void *paramBlock);
° d ONLN dG£ `Ø ó *
theMessage ° d ONLN dR£ ÃØfl )l8Contains the message to send to the File System Manager. ° d ONLN dã∑ `√ ô (¿ `
paramBlock ° d ONLN dñ∑ Ã√√ )l5Contains a pointer to optional message specific data. ° d ONLN dÃ’ `·Ï (fi `PInformFSM passes a message and optional message-specific data to the File System ° d ONLN d · `̯ * MManager. The File System Manager will return an fsmUnknownFSMMessageErr if an ° d ONLN dkÌ `˘Ï * Nundefined message is passed. The currently defined messages are fsmNopMessage, ° d ONLN d∫˘ `
* MfsmDrvQElChangedMessage, and fsmGetFSIconMessage. How the File System Manager ° d ONLN d `
* Yhandles each message and what result codes can be returned are described in the following ° d ONLN db ` ò * paragraphs.
° d ONLN dn/ `> ÿ *
fsmNopMessage ° d ONLN d{/ ÿ> Ò )x (0)
° d ONLN dÄI `U (R `XThe File System Manager does nothing. The paramBlock parameter is ignored and the result ° d ONLN dŸU `a Æ * is always noErr. ° d ONLN dÍu lÅ ® + Result codes ° d ONLN d˜Å ç ö + noErr ° d ONLN d˝Å)ç/ )™0 ° d ONLN dˇÅ<çe )No error (Ú5$File System Manager Service Routines )–1- )
17 ˇ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager , Helvetica
° d ONLN d U H d *-fsmDrvQElChangedMessage ° d ONLN d U d0 )œ (1)
° d ONLN d o H {˝ ( x HWThe fsmDrvQElChangedMessage tells the File System Manager to search the drive queue for ° d ONLN d t { H ᡠ* Zunmounted volumes and attempt to find a File System Manager controlled foreign file system ° d ONLN d œ á H ìÙ * [that can mount the volume. If a foreign file system is found that can mount the volume, the ° d ONLN d+ ì H ü * [File System Manager will issue a diskInsertEvt for the drive so the foreign file system can ° d ONLN dá ü H ´ ° * mount the volume. ° d ONLN dô ∑ T √ s + Note: ° d ONLN dû ∑ s √fl ) J Drive queue elements with the value fsmIgnoreFSID in the dQFSID field are ° d ONLN dÈ √ T œ» ( à TJignored by the File System Manager when it searches for unmounted volumes. ° d ONLN d4 · H ÌÀ ( Í HRThis message can be sent by a disk driver to notify the File System Manager that a ° d ONLN dá Ì H ˘ı * Xunmounted disk has a non-HFS partition. Before sending this message, the disk driver has ° d ONLN d‡ ˘ HÍ * [allocated a drive queue element for the partition and added it to the system’s drive queue. ° d ONLN d< H ¸ *]This message is also sent by a foreign file system’s installation code to check for unmounted ° d ONLN dö H) * /disks after a foreign file system is installed. ° d ONLN d 5 HAÄ *@The paramBlock parameter is ignored. The result is always noErr. ° d ONLN d M TY w + Note: ° d ONLN dM wY· )#IThis message can cause memory to move. A disk driver can safely make this ° d ONLN d[Y Te ˘ (b T#request only at driver accRun time. ° d ONLN d Tã ê *& Result codes ° d ONLN dåã gó Ç + noErr ° d ONLN díãó )™0 ° d ONLN dîã$óM )No error
° d ONLN dù≥ H¬ (æ HfsmGetFSIconMessage ° d ONLN d∞≥ ¬ )® (2)
° d ONLN dµÕ HŸ˙ (÷ HYThe fsmGetFSIconMessage tells the File System Manager to get a foreign file system’s disk ° d ONLN dŸ HÂm * 9icon. The paramBlock parameter points to a FSMGetIconRec. (Ú H1- )
18 )&$File System Manager Service Routines ˇÊ d ˇ ˇˇˇˇ d
d , Times
. ( 3¢The File System Manager ° d ONLN d i l u … ( r l
FSMGetIconRec , Symbol ° d ONLN d u l Ü x *Æ ° d ONLN d y Ö § )refNum ° d ONLN d y Á Ö ˇ )hshort ° d ONLN d y/ ÖÛ )H(Contains the target drive number, volume ° d ONLN d J Ü/ íÍ *
&reference number, or working directory ° d ONLN d u í/ ûS * number ° d ONLN d | û l Ø x ( ´ lÆ ° d ONLN d ~ ¢ Æ ¿ )
iconBufferPtr ° d ONLN d å ¢ Á Æ ı )hPtr ° d ONLN d ê ¢/ Æ
)H/Contains a pointer to the icon buffer where the ° d ONLN d ƒ Ø/ ª˘ *
-foreign file system will return the icon data ° d ONLN d Ú ª l à x ( » lÆ ° d ONLN d Ù ø À µ ) requestSize ° d ONLN d ø Á À ¸ )hlong ° d ONLN d ø/ Àˇ )H-Contains the size of the supplied icon buffer ° d ONLN d3 à l › x ( Ÿ l¨ ° d ONLN d5 – ‹ Æ )
actualSize ° d ONLN d@ – Á ‹ ¸ )hlong ° d ONLN dE –/ ‹ )H/The foreign file system returns the actual size ° d ONLN dy ›/ ÈØ *
of the icon data in this field ° d ONLN dò È l ˙ x ( ˆ lÆ ° d ONLN dö Ì ˘ ´ )iconType ° d ONLN d£ Ì Á ˘ ˚ )hchar ° d ONLN d® Ì/ ˘÷ )H#Contains the kind of icon requested ° d ONLN dà ˙ l x ( l¨ ° d ONLN dŒ ˛
± ) isEjectable ° d ONLN d⁄ ˛ Á
)hBoolean ° d ONLN d‚ ˛/
)H,The File System Manager returns true in this ° d ONLN d /∂ *
field if the device is ejectable ° d ONLN d4 l( x ($ l¨ ° d ONLN d6 ' ≈ )
driveQElemPtr ° d ONLN dD Á' )h DrvQElPtr ° d ONLN dN/' )H,The File System Manager returns a pointer to ° d ONLN d(/4¿ *
the drive’s DrvQEl in this field ° d ONLN d†4 lE x (A l¨ ° d ONLN d¢8 D ÷ )fileSystemSpecPtr ° d ONLN d¥8 ÁD )h FSSpecPtr ° d ONLN dæ8/D )H,The File System Manager returns a pointer to ° d ONLN dÔE/Q *
*foreign file system’s FSSpec in this field ° d ONLN dQ lb x (^ lÆ ° d ONLN d U a ≠ ) reserved1 ° d ONLN d&U Áa ¸ )hlong ° d ONLN d+U/aö )Hreserved, must be zero ° d ONLN dBr `~ ({ `YThe refNum field must contain the target drive number, volume reference number or working ° d ONLN dú~ `ä * Ydirectory number. The iconBufferPtr field must point to the buffer where the icon will be ° d ONLN dˆä `ñÔ * Vreturned. The requestSize field must contain the size of the supplied icon buffer. The ° d ONLN dMñ `¢d * 7iconType field must contain the kind of icon requested. ° d ONLN dÖÆ `∫ˇ *VThe icon kinds supported and their sizes are those used by the Desktop Manager and are ° d ONLN d‹∫ `Δ π * listed in Table 1-4. ° d ONLN dÒ“ `fi *Table
° d ONLN dˆ” fi Å )
° d ONLN d˜“ Åfi ô )1-4. ° d ONLN d¸“ ®fi › )'
Icon Types ° d ONLN dÈ Ãı ¸ +$Value or ‚ ^‚ ° d ONLN dı Ã ˘ * bytes in ° d ONLN d ıV )6
Corresponding ° d ONLN d+ `
í (
`Constant ° d ONLN d4 Ã
Ú )lbitmap ° d ONLN d;
N )6
resource type ° d ONLN dI`
° )^ Description ° d ONLN dU `% ñ (" `
kLargeIcon ° d ONLN d`% `1 ™ * kLarge4BitIcon ° d ONLN do1 `= ™ * kLarge8BitIcon ° d ONLN d~= `I ñ *
° d ONLN dìs H‚ *TUse the InformFFS function to communicate with foreign file systems through the File ° d ONLN dË Hã õ * System Manager. ,
Courier
° d ONLN d¯ò H§Ü *5pascal short InformFFS(short fsid, void *paramBlock);
° d ONLN d.Ø Hª Z *fsid ° d ONLN d3Ø ¥ª˘ )lEContains the unique file system ID (FSID) of the foreign file system. ° d ONLN dy√ Hœ Å (à H
paramBlock ° d ONLN dÑ√ ¥œ´ )l5Contains a pointer to optional message specific data. ° d ONLN d∫· HÌÎ (Í HUInformFFS passes a message through the File System Manager to the foreign file system ° d ONLN dÌ H˘” * Uspecified by fsid. The message data structure is defined by each foreign file system. ° d ONLN df
T ê + Result codes ° d ONLN ds g% Ç + noErr ° d ONLN dy ˆ% ¸ )è0 ° d ONLN d{%D )%No error ° d ONLN dÑ% g1 Œ (. gfsmFFSNotFoundErr ° d ONLN dñ% Ê1 ¸ )-431 ° d ONLN dõ%1ÿ )5(The file system descriptor with fsid was ° d ONLN d«1=û * not found in the FSD queue (Ú H1- )
20 )&$File System Manager Service Routines ˇ ä d ˇ ˇˇˇˇ d
d , Times
. ( -¢The File System Manager , Helvetica
° d ONLN d s ` ÇÆ ( ~ `$FOREIGN FILE SYSTEM-DEFINED ROUTINES l ^ l Ö ^ Ö ° d ONLN d % ® ` ∑s *5#File System Communications Function ∑ ^ ∑§
° d ONLN d I ƒ ` – *TThe communications function pointed to by fileSystemCommProc in an FSDRec is used by ° d ONLN d û – ` ‹∂ * Fthe File System Manager to communicate with a foreign file system. The ° d ONLN d  ‹ ` Ë[ * 0fileSystemCommProc must have the following form. ,
Courier
° d ONLN d ı `» *<pascal OSErr MyFSDCommProc (short message, void *paramBlock, ° d ONLN d[
Å +µ void *globalsPtr);
° d ONLN dn `$ à (! `message ° d ONLN dv Ã$· )l;Contains the message being sent to the foreign file system. ° d ONLN d≤, `8 ô (5 `
paramBlock ° d ONLN dΩ, Ã8 )lCContains a pointer to a buffer containing any additional parameters ° d ONLN d8 ÃD` * needed to process the message. ° d ONLN d L `X ê (U `
globalsPtr ° d ONLN d+L ÃX )lDContains a pointer to the foreign file system’s optional global data ° d ONLN dpX Ãd „ * area. ° d ONLN dvv `Ç ( `\When the file system communications function is called, it is passed a message and a pointer ° d ONLN d”Ç `é * ]to a buffer containing any additional parameters needed to process the message. The currently ° d ONLN d1é `öÿ * Hdefined messages are ffsNopMessage, ffsGetIconMessage, ffsIDDiskMessage, ° d ONLN dzö `¶ * QffsLoadMessage, ffsUnloadMessage, ffsIDVolMountMessage, and ffsInformMessage. How ° d ONLN dö `≤ * Xthe file system communications function should handle each message and what result codes ° d ONLN d%≤ `æ * Zshould be returned are described in the following paragraphs. If the message passed is not ° d ONLN dÄæ ` ¸ * Vrecognized or handled by your file system communications function, the function result ° d ONLN d◊ `÷K * *returned must be fsmUnknownFSMMessageErr ( ° d ONLN d K÷i )Î-438). ° d ONLN d‚ lÓ ã (Î lNote: ° d ONLN d
‚ ãÓ˚ ) O The file system communications function is not called at interrupt time. Thus, ° d ONLN d]Ó l˙˚ (˜ lNit may make Memory Manager requests and synchronous operating system requests.
° d ONLN d¨ `! – ( `
ffsNopMessage ° d ONLN dπ –! È )p (0)
° d ONLN dæ, `8 (5 `WWhen the ffsNopMessage is passed to the file system communications function, do nothing ° d ONLN d8 `D * $and always return a result of noErr. ° d ONLN d;X ld ® + Result codes ° d ONLN dHd p ö + noErr ° d ONLN dNdp )è0 ° d ONLN dPd3p\ )%No error
° d ONLN dYå `õ Ï (ó `ffsGetIconMessage ° d ONLN djå Ïõ )å (1)
° d ONLN do¶ `≤È (Ø `OThe ffsGetIconMessage is passed to the file system communications function when ° d ONLN dø≤ `æ * RInformFSM is called with fsmGetFSIconMessage. The paramBlock parameter points to a ° d ONLN dæ ` ’ * FSMGetIconRec record. +’*$File System Manager Service Routines )–1- )
21 ˇ d ˇ ˇˇˇˇ d
d , Times
. +H- Guide to the File System Manager ° d ONLN d U T a ± + 1
FSMGetIconRec , Symbol ° d ONLN d a T r ` *Æ ° d ONLN d e g q å )refNum ° d ONLN d e œ q Á )hshort ° d ONLN d e q€ )H(Contains the target drive number, volume ° d ONLN d J r ~“ *
&reference number, or working directory ° d ONLN d u ~ ä; * number ° d ONLN d | ä T õ ` ( ó TÆ ° d ONLN d ~ é g ö ® )
iconBufferPtr ° d ONLN d å é œ ö › )hPtr ° d ONLN d ê é öÚ )H/Contains a pointer to the icon buffer where the ° d ONLN d ƒ õ ß· *
-foreign file system will return the icon data ° d ONLN d Ú ß T ∏ ` ( ¥ TÆ ° d ONLN d Ù ´ g ∑ ù ) requestSize ° d ONLN d ´ œ ∑ ‰ )hlong ° d ONLN d ´ ∑Á )H-Contains the size of the supplied icon buffer ° d ONLN d3 ∏ T … ` ( ≈ T¨ ° d ONLN d5 º g » ñ )
actualSize ° d ONLN d@ º œ » ‰ )hlong ° d ONLN dE º »Ï )H/The foreign file system returns the actual size ° d ONLN dy … ’ó *
of the icon data in this field ° d ONLN dò ’ T Ê ` ( ‚ TÆ ° d ONLN dö Ÿ g  ì )iconType ° d ONLN d£ Ÿ œ  „ )hchar ° d ONLN d® Ÿ Âæ )H#Contains the kind of icon requested ° d ONLN dÃ Ê T ˜ ` ( Û TÆ ° d ONLN dŒ Í g ˆ ô ) isEjectable ° d ONLN d⁄ Í œ ˆ ˆ )hBoolean ° d ONLN d‚ Í ˆ» )H(Contains true if the device is ejectable ° d ONLN d ˜ T ` ( TÆ ° d ONLN d
˚ g ≠ )
driveQElemPtr ° d ONLN d ˚ œ )h DrvQElPtr ° d ONLN d% ˚’ )H(Contains a pointer to the drive’s DrvQEl ° d ONLN dN T ` ( TÆ ° d ONLN dP g æ )fileSystemSpecPtr ° d ONLN db œ )h FSSpecPtr ° d ONLN dl › )H+Contains a pointer to foreign file system’s ° d ONLN dú%< *
FSSpec ° d ONLN d£% T6 ` (2 TÆ ° d ONLN d•) g5 ï ) reserved1 ° d ONLN dØ) œ5 ‰ )hlong ° d ONLN d¥)5Ç )Hreserved, must be zero ° d ONLN dÀF HRˆ (O HZYour foreign file system uses iconType to determine the type of icon requested. If a known ° d ONLN d&R H^æ * Ricon type is requested, open the foreign file system’s resource file (specified by ° d ONLN dy^ Hj˝ * ]fileSystemSpecPtr) with read-only access, get the specified icon resource, copy the icon data ° d ONLN d◊j Hv„ * Y(up to requestSize bytes) into the buffer pointed to by iconBufferPtr, and then close the ° d ONLN d1v Hǯ * ^foreign file system’s resource file. Return the number of icon data bytes copied into into the ° d ONLN dêÇ Hé – * buffer in the actualSize field. ° d ONLN d∞¢ TÆ ê + Result codes ° d ONLN dΩÆ g∫ Ç + noErr ° d ONLN d√Æ ˆ∫ ¸ )è0 ° d ONLN d≈Æ∫D )%No error ° d ONLN dŒ∫ gΔ º (√ gafpItemNotFound ° d ONLN dfi∫ ‡Δ ¸ )y-5012 ° d ONLN d‰∫ΔÁ );*The icon type requested could not be found ° d ONLN dΔ g“^ (œ g2any of the result codes returned by FSpOpenResFile , Helvetica
° d ONLN dBÓ H˝ (˘ HffsIDDiskMessage ° d ONLN dRÓ ˝ „ )Ç (2)
° d ONLN dW HÛ ( HWThe ffsIDDiskMessage is passed to the file system communications function when the File ° d ONLN dØ H › * WSystem Manager intercepts a MountVol request. If the idSector field in the foreign file ° d ONLN d H,Ù * Xsystem’s HFSCIRec is not -1, the paramBlock parameter points to the disk block specified ° d ONLN d`, H8‡ * Yby the idSector field of the HFSCIRec. If the idSector field in the foreign file system’s ° d ONLN d∫8 HDÙ * WHFSCIRec is -1, the paramBlock parameter points to the parameter block used to make the ° d ONLN dD HP * ZMountVol request and the ioVRefNum field in that parameter block contains the drive number ° d ONLN dmP H\ ∫ * of the volume to mount. ° d ONLN dÖh HtÊ *YYour foreign file system should determine if the disk volume belongs to this foreign file ° d ONLN dflt HĘ * ]system and return noErr if it does. If the disk volume cannot be identified, return extFSErr. ° d ONLN d=å Hò *]If your foreign file system returns noErr and its HFS component interface code is not loaded, ° d ONLN dõò H§º * Lthe File System Manager will send your foreign file system a ffsLoadMessage. *P1- )
22 )&$File System Manager Service Routines ˇ ú d ˇ ˇˇˇˇ d
d , Times
. ( -¢The File System Manager ° d ONLN d i l u ® ( r l Result codes ° d ONLN d
u Å ö + noErr ° d ONLN d u Å )è0 ° d ONLN d u3 Å )%,The disk volume belongs to this foreign file ° d ONLN d E Å3 çT * system ° d ONLN d L ç ô ™ ( ñ extFSErr ° d ONLN d U ç ô )Ö-58 ° d ONLN d Y ç3 ô )/'The disk volume does not belong to this ° d ONLN d Ñ ô3 •ã * foreign file system , Helvetica
° d ONLN d ò ¡ ` – ◊ ( Ã `ffsLoadMessage ° d ONLN d ¶ ¡ ◊ – )w (3)
° d ONLN d ´ € ` Á ( ‰ `UThe ffsLoadMessage is passed to the file system communications function when the File ° d ONLN d Á ` Û * [System Manager needs to call the HFS component interface code of a foreign file system that ° d ONLN d] Û ` ˇ\ * 4is not loaded. The paramBlock parameter is not used. ° d ONLN dí ` *WYou should check to see if the HFS component interface code is loaded. If not, load and ° d ONLN dÍ `#˘ * Vdetach the HFS component interface code and related data, allocate a stack for the HFS ° d ONLN dA# `/Δ * Kcomponent interface code’s use, initialize the HFSCIRec in the FSD, set the ° d ONLN dç/ `; * VhfsCIResourceLoadedBit in the compInterfMask, activate the HFS component interface for ° d ONLN d‰; `G" * *the foreign file system, and return noErr. ° d ONLN dS `_ *[If the HFS component interface code cannot be loaded, the stack cannot be allocated, or the ° d ONLN dk_ `k˝ * XHFS component interface for the foreign file system cannot be activated, return an error ° d ONLN dƒk `w ~ * result. ° d ONLN dÃã ló ® + Result codes ° d ONLN dŸó £ ö + noErr ° d ONLN dfló£ )è0 ° d ONLN d·ó3£ )%)No error; the HFS component interface was ° d ONLN d£3Øœ * !successfully loaded and activated ° d ONLN d0Ø ª ∏ (∏
memFullErr ° d ONLN d;Ø ˛ª )-108 ° d ONLN d@Ø3ª… )5 The stack could not be allocated ° d ONLN daª «
(ƒ Qany of the result codes returned by the Resource Manager, GetFSInfo, or SetFSInfo
° d ONLN d≥„ `Ú Ê (Ó `ffsUnloadMessage ° d ONLN d√„ ÊÚ ˇ )Ü (4)
° d ONLN d»˝ ` ( `WThe ffsUnloadMessage is passed to the file system communications function when the File ° d ONLN d `Ú * NSystem Manager no longer needs the HFS component interface code in memory. The ° d ONLN do `! * !paramBlock parameter is not used. ° d ONLN dë- `9 *WYou should disable the HFS component interface, clear the hfsCIResourceLoadedBit in the ° d ONLN dÈ9 `E * TcompInterfMask, make the HFS component interface code and related data purgable, and ° d ONLN d>E `Q_ * 4dispose of the HFS component interface code’s stack. ° d ONLN dse lq ® + Result codes ° d ONLN dÄq } ö + noErr ° d ONLN dÜq} )è0 ° d ONLN dàq3} )%)No error; the HFS component interface was ° d ONLN dµ}3âÊ * %successfully unloaded and deactivated ° d ONLN d€â ïù (í ;any of the result codes returned by GetFSInfo, or SetFSInfo +∂_$File System Manager Service Routines )–1- )
23 ˇ™ d ˇ ˇˇˇˇ d
d , Times
. +H- Guide to the File System Manager , Helvetica
° d ONLN d U H d Ô *3ffsIDVolMountMessage ° d ONLN d U Ô d )ß (5)
° d ONLN d o H {˚ ( x HYThis message is passed to the file system communications function when the File Manager’s ° d ONLN d s { H á * ^VolumeMount routine is called to give a foreign file system a chance to claim the request. The ° d ONLN d “ á H ìÓ * TparamBlock parameter points to parameter block used to make the VolumeMount request. ° d ONLN d' ì H üÍ * VThe ioBuffer field of the parameter block points to a VolumeMountInfoHeader structure. ° d ONLN d~ ≥ T ø „ + VolumeMountInfoHeader , Symbol ° d ONLN dî ø T – ` *Æ ° d ONLN dñ √ g œ Ñ )length ° d ONLN dù √ ê œ ® ))short ° d ONLN d£ √ ÿ œÒ )H:Contains the length in bytes of the entire VolumeMountInfo ° d ONLN d‚ – ÿ ‹‘ *
8record including this field and the variable length data ° d ONLN d ‹ ÿ ËI * following the flags field ° d ONLN d9 Ë T ˘ ` ( ı TÆ ° d ONLN d; Ï g ¯ É )media ° d ONLN dA Ï ê ¯ Õ ))
VolumeType ° d ONLN dL Ï ÿ ¯ı )H:Contains the VolumeType of the media to mount. This is the ° d ONLN dã ˘ ÿ˝ *
>creator type that you registered with Apple Computer, Inc. for ° d ONLN dŒ ÿ^ * your file system ID number. ° d ONLN dÍ T" a ( T´ ° d ONLN dÏ g! ~ )flags ° d ONLN dÚ ê! ® ))short ° d ONLN d¯ ÿ!x )H Contains the volume mount flags. ° d ONLN d " ÿ3 ‰ *Æ ° d ONLN d & Í2I )volMountInteractBit ° d ONLN d2&V2˛ )l(If set, it’s safe for the file system to ° d ONLN da3V?Ù *
!perform user interaction to mount ° d ONLN dâ?VKä *
the volume ° d ONLN dóK ÿ\ ‰ (X ÿ¨ ° d ONLN dôO Í[P )volMountChangedBit ° d ONLN d¨OV[ˆ )l#If set, the file system mounted the ° d ONLN d÷\Vhˆ *
volume, but the volume mounting ° d ONLN d¸hVtÊ * information record needs to be ° d ONLN d!tVÄ * updated. ° d ONLN d*ê Tú s (ô TNote: ° d ONLN d/ê súÍ ) I The VolumeMountInfoHeader record is a superset of the VolMountInfoHeader ° d ONLN dyú T®’ (• TUrecord defined in Inside Macintosh: Files. In particular, the flags field used by the ° d ONLN dœ® T¥fl * OAppleShare file system was added to VolumeMountInfoHeader to allow foreign file ° d ONLN d ¥ T¿Œ * Ksystems to properly interact with the Alias Manager (the kARMNoUI rulesMask ° d ONLN dk¿ TÉ * Upassed to MatchAlias is used to set or clear the volMountInteractBit; MatchAlias uses ° d ONLN d¡Ã Tÿº * Ithe volMountChangedBit to determine the value returned in the needsUpdate ° d ONLN d ÿ T‰ ä * parameter). ° d ONLN dˆ HË (ˇ HTYou should compare the media field in the VolumeMountInfoHeader to your foreign file ° d ONLN dl H * Ysystem’s media type and return noEr if they match. If they do not match, return extFSErr. ° d ONLN dΔ HÊ * WYour media type should be the creator type assigned when you register your foreign file ° d ONLN d H& ì * system’s FSID. ° d ONLN d-2 H> *]If your foreign file system returns noErr and its HFS component interface code is not loaded, ° d ONLN dã> HJº * Lthe File System Manager will send your foreign file system a ffsLoadMessage. ° d ONLN dÿV HbÓ *TForeign file systems are called with the ffsIDVolMountMessage before the VolumeMount ° d ONLN d-b Hn * `request is passed to the File Manager. If your foreign file system claims the request, it should ° d ONLN dén HzÍ * Zuse this time to load data or code resources and to perform any user interaction needed to ° d ONLN dÈz HÜ∫ * Nmount the volume. User interface interactions should be performed only if the ° d ONLN d 8Ü Hí˝ * bvolMountInteract bit is set in the flags field. When the volMountInteract bit is set, it indicates ° d ONLN d õí HûÓ * Uthe caller of VolumeMount has initialized the QuickDraw, the Font Manager, the Window ° d ONLN d Òû H™z * <Manager, the Menu Manager, TextEdit, and the Dialog Manager. *J1- )
24 )&$File System Manager Service Routines ˇX d ˇ ˇˇˇˇ d
. ° d ONLN d V ` h k +`d2 ° d ONLN d V Ñ hŒ )$THE HFS COMPONENT INTERFACE Q ^ Q h ^ h , Times
(Ú 2- )
1 ˇ v d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager , Helvetica
° d ONLN d U H d Ú *-ABOUT THIS CHAPTER N F N g F g
° d ONLN d ~ H äÌ *'WThis chapter describes the HFS component interface, the data structures used by the HFS ° d ONLN d k ä H ñ * Vcomponent interface, and the routines your foreign file system must provide to the HFS ° d ONLN d ¬ ñ H ¢ ´ * component interface. ° d ONLN d ◊ Æ H ∫Î *ZTo use this chapter, you should be familiar with the information in the chapters “The File ° d ONLN d2 ∫ H ΔÔ * WSystem Manager” and “File System Utility Routines” in this document, the information in ° d ONLN dä Δ H “ ∂ * Inside Macintosh: Files ° d ONLN d° Δ ∂ “( )n, and the information in ° d ONLN d∫ Δ( “§ )rInside Macintosh: Devices ° d ONLN d” Δ§ “® )|.
° d ONLN d’ ˜ Há ( H!ABOUT THE HFS COMPONENT INTERFACE F F
° d ONLN d˜ H,˘ *'YThe HFS component interface allows a foreign file system to process File Manager requests ° d ONLN dQ, H8Ÿ * Xand allows a foreign file system to describe its file system services to the File System ° d ONLN d™8 HD˜ * YManager. Whenever a File Manager request is made to a volume controlled by a foreign file ° d ONLN dD HP¸ * ]system, the File System Manager will pass that request to the foreign file system through the ° d ONLN dbP H\ ≈ * HFS component interface.
° d ONLN d{Å HêÉ *3!USING THE HFS COMPONENT INTERFACE z Fz ì Fì
° d ONLN dù™ H∂ ∞ *'This section describes ° d ONLN d¥¬ TŒ X + • ° d ONLN d∂¬ aŒ )
"the HFS Component Interface record ° d ONLN dŸ⁄ TÊ X („ T• ° d ONLN d€⁄ aÊ Ó )
the foreign file system’s stack ° d ONLN d˚Ú T˛ X (˚ T• ° d ONLN d˝Ú a˛t )
7the HFS Component Interface request processing function ° d ONLN d5
T X ( T• ° d ONLN d7
a ˆ )
the Logical to Physical function ° d ONLN dX" T. X (+ T• ° d ONLN dZ" a. “ )
the Extend File function
° d ONLN dsF HU[ (Q H"The HFS Component Interface Record U FU
° d ONLN dñb Hnˇ *\The HFS component interface record in an File System Descriptor lets the foreign file system ° d ONLN dÛn Hz * Ytell the HFS component interface how to dispatch file system requests to the foreign file ° d ONLN dMz HÜ * ^system. It tells the HFS component interface where the routines to handle file system requests ° d ONLN d¨Ü HíÚ * Zare in memory, what disk block the foreign file system needs to identify a disk, and where ° d ONLN dí Hû * Tthe foreign file system’s stack is. The data type HFSCIRec defines the HFS component ° d ONLN d\û H™ ï * interface record. *K2- )
2 )&!Using the HFS component interface ˇŒ d ˇ ˇˇˇˇ d
d , Times
. ( 3âThe HFS Component Interface ,
Courier
° d ONLN d i l u “ ( r lstruct HFSCIRec { ° d ONLN d u ä Å ¢ + long ° d ONLN d u ˘ ÅS )ocompInterfMask; ° d ONLN d ' ui ÅÁ )p/* component flags */ ° d ONLN d = Å ä ç ∫ ( ä äHFSCIUPP ° d ONLN d F Å ˘ çS )ocompInterfProc; ° d ONLN d V Åi çˇ )p/* pointer to file system ° d ONLN d u ç{ ô + request processing code */ ° d ONLN d ê ô ä • Δ ( ¢ ä
Lg2PhysUPP ° d ONLN d õ ô ˘ •A )o log2PhyProc; ° d ONLN d ® ôi • )p /* pointer to Lg2PhysProc */ ° d ONLN d ≈ • ä ± ú ( Æ äPtr ° d ONLN d … • ˘ ±/ )o stackTop; ° d ONLN d ” •i ± )p/* file system stack top */ ° d ONLN d Ô ± ä Ω ¢ ( ∫ älong ° d ONLN d Ù ± ˘ Ω5 )o
stackSize; ° d ONLN d ˇ ±i Ω· )p/* file system stack ° d ONLN d Ω{ …• + size */ ° d ONLN d! … ä ’ ú ( “ äPtr ° d ONLN d% … ˘ ’/ )o stackPtr; ° d ONLN d/ …i ’Ì )p/* current file system ° d ONLN dK ’{ ·€ + stack pointer */ ° d ONLN d\ · ä Ì ¢ ( Í älong ° d ONLN da · ˘ Ì5 )o
reserved3; ° d ONLN dl ·i ÌÌ )p/* --reserved, must be ° d ONLN dà Ì{ ˘± + zero-- */ ° d ONLN dí ˘ ä ¢ ( älong ° d ONLN dó ˘ ˘/ )o idSector; ° d ONLN d° ˘i )p/* Sector you need to ID a ° d ONLN d¡{· + local volume. For ° d ONLN dÿ{ * networked volumes, this ° d ONLN dı {)€ * should be -1. */ ° d ONLN d) ä5 ¢ (2 älong ° d ONLN d ) ˘55 )o
reserved2; ° d ONLN d)i5Ì )p/* --reserved, must be ° d ONLN d25{A± + zero-- */ ° d ONLN d<A äM ¢ (J älong ° d ONLN dAA ˘M5 )o
reserved1; ° d ONLN dLAiMÌ )p/* --reserved, must be ° d ONLN dhM{Y± + zero-- */ ° d ONLN drY äe ñ (b ä}; ° d ONLN due äqP * !typedef struct HFSCIRec HFSCIRec; ° d ONLN dóq ä}> * typedef HFSCIRec *HFSCIRecPtr;
° d ONLN d∂é `ö Δ (ó `Field descriptions ° d ONLN d…® `¥ Æ *compInterfMask ° d ONLN dÿ® Ã¥ )lAContains the HFS component interface dispatch mask. Currently the ° d ONLN d¥ ÿH * following bits are defined: ° d ONLN d6¿ Ãà › * Bit ° d ONLN d;¿eÃï )ôMeaning ° d ONLN dCà Ãÿ ‚ (’ Ã0-17 ° d ONLN dIÃeÿï )ô Reserved. ° d ONLN dSÿ É ÿ (· Ã18 ° d ONLN dVÿ Á‰J )hfsCIHLL2PProcBit ° d ONLN dhÿe‰˛ )~"Set this bit if the log2PhyProc is ° d ONLN dé‰e * &written in a high level language using ° d ONLN d∏e¸ * &Pascal calling conventions. Note: this ° d ONLN d‚¸e
* #bit should always be set by foreign ° d ONLN d e˘ * !file systems using the logical to ° d ONLN d.e * $physical interface described in this ° d ONLN dV e,ã * chapter. ° d ONLN d_, Ã8 ÿ (5 Ã19 ° d ONLN db, Á8_ )hfsCIResourceLoadedBit ° d ONLN dy,e8 )~"Set this bit if the HFSCIProc code ° d ONLN dü8eDˇ * "resource is loaded. If the foreign ° d ONLN d≈DeP * #file system doesn’t support dynamic ° d ONLN dÏPe\ * "loading, this bit should always be ° d ONLN d\ehv * set. ° d ONLN dh Ãt ÿ (q Ã20 ° d ONLN dh Át^ )hfsDoesDynamicLoadBit ° d ONLN d0het )~#Set this bit if dynamically loading ° d ONLN dWteÄÁ * code resource is supported. ° d ONLN dsÄ Ãå ÿ (â Ã21 ° d ONLN dvÄ ÁåS )hfsCIDoesDeskTopBit ° d ONLN däÄeå˜ )~ Set this bit if Desktop Manager ° d ONLN d≠åeò * %requests are supported. Obsolete, but ° d ONLN d÷òe§ * "should be set. Current versions of ° d ONLN d¸§e∞ * FSM always pass Desktop Manager ° d ONLN d ∞eº * $requests on to foreign file systems. (ÚB!Using the HFS component interface )…2- )
4 )&!Using the HFS component interface ˇ6 d ˇ ˇˇˇˇ d
d , Times
. ( 3âThe HFS Component Interface , Helvetica
° d ONLN d U ` dH ( ` ` The Foreign File System’s Stack d ^ d
° d ONLN d q ` } *YEach foreign file system must have its own alternate stack. The File System Manager’s HFS ° d ONLN d z } ` ⢠* Ycomponent interface saves the original application stack and switches to the foreign file ° d ONLN d ‘ â ` ï * ^system’s alternate stack before calling the foreign file system’s request processing function. ° d ONLN d3 ï ` °
* ZAfter the foreign file system services the File Manager request, The File System Manager’s ° d ONLN dé ° ` ≠∑ * HHFS component interface switches back to the original application stack. ° d ONLN d◊ π ` ≈ *\If the foreign file system performs I/O through the File System Utility cached I/O routines, ° d ONLN d4 ≈ ` —
* [there will be an additional stack switch while the HFS file system handles the I/O. Foreign ° d ONLN dê — ` ›œ * Pfile system Logical to Physical routines run on the foreign file system’s stack. ° d ONLN d· È ` ı· *SThe foreign file system’s alternate stack must be allocated in the system heap with ° d ONLN d5 ı `˜ * UNewPtrSys before the HFS component interface is activated. If the foreign file system ° d ONLN dã `
* \supports dynamically loading code resources, the stack can be allocated when the file system ° d ONLN dË
`˜ * Tcommunications function is called with the ffsLoadMessage and released when the file ° d ONLN d= `%≠ * Csystem communications function is called with the ffsUnloadMessage. ° d ONLN dÅ1 `=˘ *WThe size of a foreign file system’s alternate stack should be the amount needed by your ° d ONLN dŸ= `I * _foreign file system plus two or three kilobytes of additional space for use by interrupt driven ° d ONLN d9I `Uß * Cprocesses which may borrow space at interrupt time from your stack.
° d ONLN d}m `| *&7The HFS Component Interface Request Processing Function | ^|
° d ONLN dµâ `ï *YThe HFS Component Interface request processing function pointed to by compInterfProc in a ° d ONLN dï `° * VHFSCIRec is called by the File System Manager to handle File Manager requests. The HFS ° d ONLN df° `≠€ * MComponent Interface request processing function must have the following form. ,
Courier
° d ONLN d¥∫ `Δ™ *7pascal OSErr HFSCIProc(VCBPtr theVCB, short selectCode, ° d ONLN dÛΔ ˜“] +ó void *paramBlock,
° d ONLN dΔ]“` )f
° d ONLN dΔ`““ )void *fsdGlobalPtr, ° d ONLN d “ ˜fi? (€ ˜ short fsid);
° d ONLN d-È `ı Ü (Ú `theVCB ° d ONLN d4È Ãı )lEContains a pointer to the VCB of the volume that is the target of the ° d ONLN dzı Ã( * file system request. ° d ONLN dè ` ì ( `
selectCode ° d ONLN dö ï )l=Contains either the A-Trap number or the HFSDispatch selector ° d ONLN dÿ Ã!Á * 9number which indicates what file system request was made. ° d ONLN d) `5 ô (2 `
paramBlock ° d ONLN d ) Ã5 )lCContains a pointer to the parameter block passed to the file system ° d ONLN da5 ÃA Ú * request. ° d ONLN djI `U ù (R ` fsdGlobalPtr ° d ONLN dwI ÃU )lDContains a pointer to the foreign file system’s optional global data ° d ONLN dºU Ãa „ * area. ° d ONLN d¬i `u r (r `fsid ° d ONLN d«i Ãuª )l1Contains the file system ID number of the volume. +vÄ!Using the HFS component interface )…2- )
° d ONLN d@ µ T ¡ _ + s ° d ONLN dB ∂ f ¬ ö )Warning: ° d ONLN dJ ∂ ö ¬‚ )4F When the foreign file system’s HFSCIProc is called, the foreign file ° d ONLN dë ¬ f ŒÀ ( À fHsystem cannot do anything which might cause another File Manager request ° d ONLN d⁄ Œ f ⁄› * Qbecause the File Manager is single-threaded and is not reentrant. If your foreign ° d ONLN d, ⁄ f ÊÈ * Nfile system’s HFSCIProc does cause another File Manager request, the Macintosh ° d ONLN d{ Ê f Ú – * system will deadlock.
° d ONLN dë Ë – Ò ÿ )js
° d ONLN dì H¯ (
H\The HFSCIProc is also passed a pointer to the foreign file system’s global data area and the ° d ONLN d H ˇ * [file system ID number of the volume. The file system ID number allows a foreign file system ° d ONLN dL H(˙ * ]that handles multiple file systems to quickly determine which file system needs to handle the ° d ONLN d™( H4 § * file system request. ° d ONLN døH TT ê + Result codes ° d ONLN dÃT g` Ç + noErr ° d ONLN d“T ˆ` ¸ )è0 ° d ONLN d‘T`ı )%-The foreign file system handled the Macintosh ° d ONLN d`lπ * "file system request with no errors ° d ONLN d(l gx (u gTany of the result codes documented for a particular Macintosh file system request in ° d ONLN d}x gÑ ’ * Inside Macintosh: Files ° d ONLN dïö H¶¸ (£ H[Listing 2-1 is an abbreviated example of a request processing function. Not all HFSDispatch ° d ONLN dÒ¶ H≤õ * Fselectors and Macintosh file system A-Traps are shown in this example. ° d ONLN d8æ | ¿ +4 Listing 2-1. ° d ONLN dDæ ¿ Œ )D5 HFS Component Interface request processing function ,
Courier
° d ONLN dz” Hflí (‹ H7/* Prototype for file system request handler routine */ ° d ONLN d≤fl HÎ∞ * <typedef OSErr (*hfsProcPtr)(VCBPtr theVCB, short selectCode, ° d ONLN d˙Î ¸˜⁄ +¥ %void *paramBlock, void *fsdGlobalPtr, ° d ONLN d+˜ ¸D * short fsid); ° d ONLN d9 H ê ( H pascal OSErr ° d ONLN dF ¢§ )Z+HFSCIProc (VCBPtr theVCB, short selectCode, ° d ONLN d| Í'» +H %void *paramBlock, void *fsdGlobalPtr, ° d ONLN d¨' Í3, * short fsid) ° d ONLN d∏3 H? N (< H{ ° d ONLN dª? ZK x + OSErr ° d ONLN d√? ¢K )Hresult = extFSErr; ° d ONLN d◊K ZW ñ (T Z
hfsProcPtr ° d ONLN d„K ¥W ‰ )ZhfsProc; ° d ONLN dÌW Zc Æ (` Zunsigned short ° d ONLN d¸W ¥c Í )Z trapWord; ° d ONLN d o Z{‘ (x Z?/* selectCode contains the trap word or HFSDispatch selector */ ° d ONLN dJ{ Zá⁄ * @/* Clear the trap attributes (i.e., async and immediate bits) */ ° d ONLN dåá Zì * trapWord = selectCode & 0xF0FF; ° d ONLN dØü Z´¯ *E/* and find out what to call with the big, big switch statement... */ ° d ONLN dˆ´ Z∑ ¿ * switch (trapWord) ° d ONLN d ∑ Z√ ` * {
(Ú H2- )
6 )&!Using the HFS component interface ˇ > d ˇ ˇˇˇˇ d
° d ONLN d U Z aŒ ++>/* Call the appropriate file system request handler routine */ ° d ONLN d @ a Z m¯ * Eresult = hfsProc(theVCB, selectCode, paramBlock, fsdGlobalPtr, fsid); ° d ONLN d á m Z y ¥ * return(result); ° d ONLN d ó y H Ö N ( Ç H} , Helvetica
° d ONLN d ô û H ≠ô *'*Handling MountVol and VolumeMount requests
° d ONLN d ƒ ∏ H ƒˆ *YThere are two File Manager requests sent to a foreign file system’s HFSCIProc that may or ° d ONLN d ƒ H –fi * Qmay not be handled by your foreign file system, MountVol (selectCode = $A00F) and ° d ONLN dp – H ‹˝ * VVolumeMount (selectCode = $0041). The File System Manager sends those requests to each ° d ONLN d« ‹ H ˯ * ainstalled foreign file system until one of the foreign file systems indicates that it has handled ° d ONLN d) Ë H Ù * the request. ° d ONLN d6 H ˝ *]If your foreign file system receives a MountVol request, it must determine if the disk volume ° d ONLN dî H˜ * [belongs to it. You may be able to use the same code your foreign file system used to handle ° d ONLN d H$˝ * [the ffsIDDiskMessage is passed to the file system communications function. If the volume is ° d ONLN dL$ H0¯ * Xnot your volume, you must return extFSErr. If the volume is your volume, you must return ° d ONLN d•0 H<‹ * WnoErr if you successfully mount the volume, or one of the error result codes listed for ° d ONLN d˝< HH * &PBMountVol in Inside Macintosh: Files. ° d ONLN d$T H`˘ *WIf your foreign file system receives a VolumeMount request and supports the VolumeMount ° d ONLN d|` HlÚ * Trelated selectors (VolumeMount, GetVolMountInfoSize, and GetVolMountInfo), it should ° d ONLN d—l Hx˙ * Xcompare the media field in the VolumeMountInfoHeader to your foreign file system’s media ° d ONLN d*x HÑÙ * \type. If the media field does not match your media type, return extFSErr. If the media field ° d ONLN dáÑ HêÚ * Wmatches your media type, you must return noErr if you successfully mount the volume, or ° d ONLN dflê HúÙ * Zone of the error result codes listed for PBVolumeMount in Inside Macintosh: Files. If your ° d ONLN d:ú H®Á * Xforeign file system does not support the VolumeMount related selectors, it should return ° d ONLN dì® H¥ x * paramErr.
° d ONLN dùÃ H€û *&.The Logical to Physical Block Mapping Function € F€
° d ONLN dÃË HÙˇ *\The Macintosh cache routines described in “File System Utility Routines” chapter can read or ° d ONLN d)Ù H Ú * [write either logical blocks of a file or physical blocks of a volume. However, because disk ° d ONLN dÖ H * ^driver device requests always read or write physical blocks of a volume, a foreign file system ° d ONLN d‰ HÙ * \must provide a routine to map logical file blocks to physical volume blocks. That routine is ° d ONLN dA H$¯ * `called the logical to physical routine. The address of the logical to physical routine is passed ° d ONLN d¢$ H0˘ * Yto the File System Manager in the log2PhyProc field of the foreign file system’s HFSCIRec ° d ONLN d¸0 H<Ê * Xand as a parameter to some cache routines. The logical to physical routine must have the ° d ONLN d U< HH î * following form.
° d ONLN d eU HaP *,pascal OSErr Lg2PhysProc(void *fsdGlobalPtr, ° d ONLN d òa flmi +ó VCBPtr volCtrlBlockPtr, ° d ONLN d ∂m flyÅ * FCBRecPtr fileCtrlBlockPtr, ° d ONLN d ÿy flÖE * short fileRefNum, ° d ONLN d Ö flëÅ * unsigned long filePosition, ° d ONLN d
* ErequestCount, into the field referred to by this parameter. The value ° d ONLN dY Ãeé * )returned must be a multiple of 512 bytes. ° d ONLN d9w `É (Ä `bIt is the responsibility of the foreign file system to return an eofErr when a request for data is ° d ONLN dúÉ `è˙ * ]beyond the current logical end of file (before calling the Cache utility routines). It is the ° d ONLN d˙è `õ * `responsibility of the logical to physical routine to return an eofErr error when a cache routine ° d ONLN d[õ `ßã * ?asks for block mapping beyond the current physical end of file. ° d ONLN dõª l« ® + Result codes ° d ONLN d®« ” ö + noErr ° d ONLN dÆ«” )è0 ° d ONLN d∞«3” )%*Logical to physical mapping was successful ° d ONLN d€” fl ù (‹ eofErr ° d ONLN d‚”fl )Ö-39 ° d ONLN dÊ”3fl› )/ Requested mapping was beyond the ° d ONLN d
fl3Îç * physical end of file ° d ONLN d Î ˜ ó (Ù ioErr ° d ONLN d%Θ )Ö-36 ° d ONLN d)Î3˜ )/-Mapping failed because of an unexpected error ° d ONLN dW
10 )&!Using the HFS component interface ˇ Ï d ˇ ˇˇˇˇ d
d , Helvetica
. ° d ONLN d V ` h k +`d3 ° d ONLN d V Ñ hË )$ THE FILE SYSTEM UTILITY ROUTINES Q ^ Q h ^ h , Times
(Ú
3- )
1 ˇ z d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager , Helvetica
° d ONLN d U H d Ú *-ABOUT THIS CHAPTER N F N g F g
° d ONLN d ~ H ä‚ *'WThis chapter describes the utility routines provided by the File System Manager to your ° d ONLN d k ä H ñfl * Yforeign file system to help it process Macintosh file system calls and describes the data ° d ONLN d ≈ ñ H ¢ * -structures used by the Macintosh file system. ° d ONLN d Û Æ H ∫Î *XTo use this chapter, you should be familiar with the information in the chapter “The HFS ° d ONLN dL ∫ H Δ_ * :Component Interface” in this document, the information in ° d ONLN dÜ ∫_ ΔÕ ( √_Inside Macintosh: Files ° d ONLN dù ∫Õ Δˆ )n , and the ° d ONLN dß Δ H “ é ( œ Hinformation in ° d ONLN d∂ Δ é “
)FInside Macintosh: Devices ° d ONLN dœ Δ
“ )|.
° d ONLN d— ˜ Hz ( H"ABOUT FILE SYSTEM UTILITY ROUTINES F F
° d ONLN dı H, *'[The File System Utility routines are intended for use by foreign file systems to allow your ° d ONLN dQ, H8 ¨ * foreign file system to ° d ONLN dhD TP X + • ° d ONLN djD aPÚ )
Raccess file control blocks (FCBs), volume control blocks (VCBs), working directory ° d ONLN dΩP a\Ñ * 9control blocks (WDCBs), and drive queue elements (DrvQEl) ° d ONLN d˜h Tt X (q T• ° d ONLN d˘h atY )
4set and get the default volume and working directory ° d ONLN d.Ä Tå X (â T• ° d ONLN d0Ä aå § )
eject a volume ° d ONLN d?ò T§ X (° T• ° d ONLN dAò a§≥ )
Gvalidate and process parameters passed with Macintosh file system calls ° d ONLN dâ∞ Tº X (π T• ° d ONLN dã∞ aº√ )
Kaccess the Macintosh file system’s cache buffers and low-level I/O services ,
Zapf Dingbats
° d ONLN d◊» T‘ _ (“ Ts ° d ONLN dŸ… f’ ö )Warning: ° d ONLN d·… ö’ )4G File System Utility routines that can cause I/O through the Macintosh ° d ONLN d)’ f·≠ (fi f>file system’s cache, UTGetBlock, UTReleaseBlock, UTFlushCache, ° d ONLN dh· fÌÍ * LUTCacheReadIP, and UTCacheWriteIP, must be called from a foreign file system ° d ONLN dµÌ f˘Ë * Qhandling a request through its HFSCIProc. Attempts to call those routines outside ° d ONLN d˘ fÅ * ;of the context of the HFSCIProc will cause a system crash.
° d ONLN dB˚Åâ (Ås
° d ONLN dD0 H?® (; H%MACINTOSH FILE SYSTEM DATA STRUCTURES ) F) B FB
° d ONLN djY Hefi *'XThis section describes the data structures used internally by the Macintosh file system. ° d ONLN d√e Hqˆ * [Foreign file systems need to access and manipulate these data strutures when handling calls ° d ONLN d q H} * !from the HFS component interface. ° d ONLN dAâ Hï Δ *The data structures include ° d ONLN d]° T≠ X + • ° d ONLN d_° a≠ Ú )
volume control blocks (VCBs) ° d ONLN d|π T≈ X (¬ T• ° d ONLN d~π a≈ › )
file control blocks (FCBs) (Ú H3- )
2 )&%Macintosh File System Data Structures ˇ“ d ˇ ˇˇˇˇ d
d , Times
. ( 3Ä The File System Utility Routines ° d ONLN d U l a p ( ^ l• ° d ONLN d U y aG )
(working directory control blocks (WDCBs) ° d ONLN d + m l y p ( v l• ° d ONLN d - m y y )
° d ONLN d% › ` È *YEach time a volume is mounted, a foreign file system must allocate a volume control block ° d ONLN d È ` ı * Z(VCB) with UTAllocateVCB, read the volume and use the information to initialize the fields ° d ONLN d⁄ ı `¸ * Lin the new VCB, and add the VCB to the VCB queue with UTAddNewVCB (unless an ° d ONLN d' `
* Uejected or offline volume is being remounted). When a volume is unmounted, its VCB is ° d ONLN d}
`C * (removed from the VCB queue UTDisposeVCB. ° d ONLN d¶% `1ˇ *UThe volume control block queue is a standard Operating System queue maintained in the ° d ONLN d¸1 `= * Ysystem heap. It contains a volume control block for each mounted volume. A volume control ° d ONLN dV= `I * _block is a nonrelocatable block that contains volume-specific information. If your foreign file ° d ONLN d∂I `U * Ysystem needs to keep additional information beyond that kept in the system VCB structure, ° d ONLN dU `a * Vyou can allocate additional memory with UTAllocateVCB for your extended VCB structure. ° d ONLN dga `m€ * OThe structure of a system volume control block is defined by the VCB data type. ,
Courier
° d ONLN d∑Ç lé ¥ + ! struct VCB { ° d ONLN d≈Ç\éh )/* ° d ONLN d»Çné¯ )volume control block */ ° d ONLN d‡é äö ∫ (ó äQElemPtr ° d ONLN dÈé ö )fqLink; ° d ONLN dé\öh )l/* ° d ONLN dÛénö‡ )next queue entry */ ° d ONLN dö ä¶ ® (£ äshort ° d ONLN d
ö ¶ )fqType; ° d ONLN dö\¶h )l/* ° d ONLN dön¶º )
queue type */ ° d ONLN d%¶ ä≤ ® (Ø äshort ° d ONLN d+¶ ≤& )f vcbFlags; ° d ONLN d5¶\≤h )l/* ° d ONLN d8¶n≤» )volume flags */ ° d ONLN dH≤ äæ fi (ª äunsigned short ° d ONLN dW≤ æ2 )f vcbSigWord; ° d ONLN dc≤\æh )l/* ° d ONLN df≤næ‡ )volume signature */ ° d ONLN dzæ ä ÿ (« ä
unsigned long ° d ONLN dàæ , )f
vcbCrDate; ° d ONLN dìæ\ h )l/* ° d ONLN dñæn ¯ )date and time of volume ° d ONLN d≥ n÷∞ * creation */ ° d ONLN dø÷ ä‚ ÿ (fl ä
unsigned long ° d ONLN dÕ÷ ‚& )f vcbLsMod; ° d ONLN d◊÷\‚h )l/* ° d ONLN d⁄÷n‚Ï )date and time of last ° d ONLN dı‚nÓ∂ * modification ° d ONLN dÓ ä˙ ® (˜ äshort ° d ONLN dÓ ˙ )fvcbAtrb; ° d ONLN dÓ\˙h )l/* ° d ONLN dÓn˙Ê )volume attributes */ ° d ONLN d)˙ ä fi ( äunsigned short ° d ONLN d8˙ & )f vcbNmFls; ° d ONLN dB˙\h )l/* ° d ONLN dE˙n¯ )number of files in root ° d ONLN dbn∂ * directory */ ° d ONLN do ä ® ( äshort ° d ONLN du & )f vcbVBMSt; ° d ONLN d\ h )l/* ° d ONLN dÇn Ï )first block of volume ° d ONLN dù n*§ * bitmap */ ° d ONLN dß* ä6 ® (3 äshort ° d ONLN d≠* 68 )f vcbAllocPtr; ° d ONLN d∫*\6h )l/* ° d ONLN dΩ*n6˛ )start of next allocation ° d ONLN d€6nB§ * search */ ° d ONLN dÂB äN fi (K äunsigned short ° d ONLN dÙB N8 )f vcbNmAlBlks; ° d ONLN dB\Nh )l/* ° d ONLN dBnN )number of allocation blocks ° d ONLN d%NnZ∂ * in volume */ ° d ONLN d2Z äf ÿ (c ä
unsigned long ° d ONLN d@Z f8 )f vcbAlBlkSiz; ° d ONLN dMZ\fh )l/* ° d ONLN dPZnf⁄ )size (in bytes) of ° d ONLN dhfnr‘ * allocation blocks ° d ONLN dzr ä~ ÿ ({ ä
unsigned long ° d ONLN dàr ~, )f
vcbClpSiz; ° d ONLN dìr\~h )l/* ° d ONLN dñrn~Ï )default clump size */ ° d ONLN d¨~ ää ® (á äshort ° d ONLN d≤~ ä, )f
vcbAlBlSt; ° d ONLN dΩ~\äh )l/* ° d ONLN d¿~nä )first allocation block in ° d ONLN dflänñ§ * volume */ ° d ONLN dÈñ ä¢ ¢ (ü älong ° d ONLN dÓñ ¢2 )f vcbNxtCNID; ° d ONLN d˙ñ\¢h )l/* ° d ONLN d˝ñn¢˛ )next unused catalog node ° d ONLN d¢nÆå * ID */ ° d ONLN d!Æ ä∫ fi (∑ äunsigned short ° d ONLN d0Æ ∫2 )f vcbFreeBks; ° d ONLN d<Æ\∫h )l/* ° d ONLN d?Æn∫ )number of unused allocation ° d ONLN d`∫nΔ§ * blocks */ ° d ONLN djΔ ä“ ® (œ äStr27 ° d ONLN dpΔ “ )fvcbVN; ° d ONLN dwΔ\“h )l/* ° d ONLN dzΔn“¬ )volume name */
(Ú5%Macintosh File System Data Structures )÷3- )
3 ˇF d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ,
Courier
° d ONLN d U r a ê +*+short ° d ONLN d U ÿ a )f
vcbDrvNum; ° d ONLN d UD aP )l/* ° d ONLN d UV a∞ )drive number */ ° d ONLN d $ a r m ê ( j rshort ° d ONLN d * a ÿ m )f vcbDRefNum; ° d ONLN d 6 aD mP )l/* ° d ONLN d 9 aV mÚ )driver reference number */ ° d ONLN d T m r y ê ( v rshort ° d ONLN d Z m ÿ y )fvcbFSID; ° d ONLN d c mD yP )l/* ° d ONLN d f mV yÏ )file-system identifier */ ° d ONLN d Ä y r Ö ê ( Ç rshort ° d ONLN d Ü y ÿ Ö )f vcbVRefNum; ° d ONLN d í yD ÖP )l/* ° d ONLN d ï yV ÖÚ )volume reference number */ ° d ONLN d ∞ Ö r ë Ñ ( é rPtr ° d ONLN d ¥ Ö ÿ ë )fvcbMAdr; ° d ONLN d Ω ÖD ëP )l/* ° d ONLN d ¿ ÖV ë¬ )used internally */ ° d ONLN d ” ë r ù Ñ ( ö rPtr ° d ONLN d ◊ ë ÿ ù )f
vcbDirBlk; ° d ONLN dW µD ¡P )l/* ° d ONLN dZ µV ¡¬ )used internally */ ° d ONLN dm ¡ r Õ ¿ ( r
unsigned long ° d ONLN d{ ¡ ÿ Õ )f vcbVolBkUp; ° d ONLN dá ¡D ÕP )l/* ° d ONLN dä ¡V Õ‘ )date and time of last ° d ONLN d• ÕV Ÿå * backup */ ° d ONLN dØ Ÿ r Â Δ ( ‚ runsigned short ° d ONLN dæ Ÿ ÿ  )f vcbVSeqNum; ° d ONLN d ŸD ÂP )l/* ° d ONLN dÕ ŸV Â⁄ )volume backup sequence ° d ONLN dÈ ÂV Òå * number */ ° d ONLN dÛ Ò r ˝ ä ( ˙ rlong ° d ONLN d¯ Ò ÿ ˝ )f vcbWrCnt; ° d ONLN d ÒD ˝P )l/* ° d ONLN d ÒV ˝‘ )volume write count */ ° d ONLN d ˝ r ä ( rlong ° d ONLN d ˝ ÿ )f vcbXTClpSiz; ° d ONLN d- ˝D P )l/* ° d ONLN d0 ˝V ⁄ )clump size for extents ° d ONLN dL V∂ * overflow file */ ° d ONLN d] r! ä ( rlong ° d ONLN db ÿ! )f vcbCTClpSiz; ° d ONLN doD!P )l/* ° d ONLN drV!⁄ )clump size for catalog ° d ONLN dé!V-Ä * file */ ° d ONLN dñ- r9 Δ (6 runsigned short ° d ONLN d•- ÿ9 )f vcbNmRtDirs; ° d ONLN d≤-D9P )l/* ° d ONLN dµ-V9Ê )number of directories in ° d ONLN d”9VEò * root dir */ ° d ONLN dflE rQ ä (N rlong ° d ONLN d‰E ÿQ )f
vcbFilCnt; ° d ONLN dÔEDQP )l/* ° d ONLN dÚEVQ¬ )number of files in ° d ONLN d
QV]å * volume */ ° d ONLN d] ri ä (f rlong ° d ONLN d] ÿi )f
vcbDirCnt; ° d ONLN d$]DiP )l/* ° d ONLN d']ViÊ )number of directories in ° d ONLN dEiVuå * volume */ ° d ONLN dOu rÅ ä (~ rlong ° d ONLN dTu ÿÅ2 )fvcbFndrInfo[8]; ° d ONLN dduDÅP )l/* ° d ONLN dguVŇ )information used by the ° d ONLN dÑÅVçå * Finder */ ° d ONLN déç rô Δ (ñ runsigned short ° d ONLN dùç ÿô )f
vcbVCSize; ° d ONLN d®çDôP )l/* ° d ONLN d´çVô¬ )used internally */ ° d ONLN dæô r• Δ (¢ runsigned short ° d ONLN dÕô ÿ• )f vcbVBMCSiz; ° d ONLN dŸôD•P )l/* ° d ONLN d‹ôV•¬ )used internally */ ° d ONLN dÔ• r± Δ (Æ runsigned short ° d ONLN d˛• ÿ± )f vcbCtlCSiz; ° d ONLN d
•D±P )l/* ° d ONLN d
•V±¬ )used internally */ ° d ONLN d ± rΩ Δ (∫ runsigned short ° d ONLN d/± ÿΩ )f vcbXTAlBlks; ° d ONLN d<±DΩP )l/* ° d ONLN d?±VΩÊ )size of extents overflow ° d ONLN d]ΩV…Ä * file */ ° d ONLN de… r’ Δ (“ runsigned short ° d ONLN dt… ÿ’ )f vcbCTAlBlks; ° d ONLN dÅ…D’P )l/* ° d ONLN dÑ…V’‡ )size of catalog file */ ° d ONLN dú’ r· ê (fi rshort ° d ONLN d¢’ ÿ· )f vcbXTRef; ° d ONLN d¨’D·P )l/* ° d ONLN dØ’V·‘ )ref. num. for extents ° d ONLN d ·VÌ∂ * overflow file */ ° d ONLN d€Ì r˘ ê (ˆ rshort ° d ONLN d·Ì ÿ˘ )f vcbCTRef; ° d ONLN dÎÌD˘P )l/* ° d ONLN dÓÌV˘‘ )ref. num. for catalog ° d ONLN d ˘VÄ * file */ ° d ONLN d r Ñ ( rPtr ° d ONLN d ÿ )f
vcbCtlBuf; ° d ONLN d DP )l/* ° d ONLN d#V¯ )ptr. to extents and catalog ° d ONLN dDV å * caches */ ° d ONLN dN r) ä (& rlong ° d ONLN dS ÿ) )f
vcbDirIDM; ° d ONLN d^ D)P )l/* ° d ONLN da V)Ú )directory last searched */ ° d ONLN d|) r5 ê (2 rshort ° d ONLN dÇ) ÿ5 )f vcbOffsM; ° d ONLN då)D5P )l/* ° d ONLN dè)V5‡ )offspring index at last ° d ONLN d¨5VAå * search */ ° d ONLN d∂A rM ~ (J r}; ° d ONLN dπM rY ¸ * typedef struct VCB VCB; ° d ONLN d—Y re Í * typedef VCB *VCBPtr;
° d ONLN dÊv HÇ Æ ( HField descriptions ° d ONLN d˘ê Hú d *qLink ° d ONLN dˇê ¥úı )lGA pointer to the next entry in the VCB queue. This field is initialized ° d ONLN dGú ¥®‰ * 6when the VCB is added to the VCB queue by UTAddNewVCB. ° d ONLN d~∞ Hº f (π HqType ° d ONLN dÑ∞ ¥º˚ )lFThe queue type. This field is initialized when the VCB is added to the ° d ONLN dÀº ¥»T * VCB queue by UTAddNewVCB. (Ú H3- )
4 )&%Macintosh File System Data Structures ˇf d ˇ ˇˇˇˇ d
d , Times
. ( 3Ä The File System Utility Routines ° d ONLN d U ` a ã ( ^ `vcbFlags ° d ONLN d U à a )lCVolume flags. Set bit 15 if the volume information has been changed ° d ONLN d M a à mÓ * >by a File Manager call since the volume was last affected by a ° d ONLN d å m à y * FlushVol call. ° d ONLN d õ Å ` ç ú ( ä `
vcbSigWord ° d ONLN d ¶ Å Ã çœ )l6The volume signature. This field must be set to $4244. ° d ONLN d › ï ` ° í ( û ` vcbCrDate ° d ONLN d Á ï à ° )lJSet to the date and time of volume creation (initialization), specified as ° d ONLN d2 ° à ≠◊ * 6the number of seconds since midnight, January 1, 1904. ° d ONLN di µ ` ¡ ì ( æ `vcbLsMod ° d ONLN dr µ à ¡ )lISet to the date and time of last modification, specified as the number of ° d ONLN dº ¡ Ã Õ˛ * @seconds since midnight, January 1, 1904. This is not necessarily ° d ONLN d˝ Õ Ã Ÿp * !when the volume was last flushed. ° d ONLN d · ` Ì Ü ( Í `vcbAtrb ° d ONLN d' · à Ì≥ )l0Volume attributes. The bits have these meanings: ° d ONLN dX Ì Ã ˘ › * Bit ° d ONLN d\ Ì ˘2 )6Meaning ° d ONLN dd ˘ à fi ( Ã0–5 ° d ONLN dh ˘2 )6 Reserved. ° d ONLN dr à “ ( Ã6 ° d ONLN dt )69Set this bit if the volume is busy (one or more files are ° d ONLN dØ ! * open). ° d ONLN d∂ Ã) “ (& Ã7 ° d ONLN d∏ ) )6:Set this bit if the volume is locked by hardware. This can ° d ONLN dı)5Ï * /be obtained when the volume is mounted with the ° d ONLN d'5Ag * DriveStatus function. ° d ONLN d=A ÃM ‰ (J Ã8–14 ° d ONLN dBAM2 )6 Reserved. ° d ONLN dLM ÃY ÿ (V Ã15 ° d ONLN dOMY )6:Set this bit if the volume is locked by software. This bit ° d ONLN dåYe * 6can be set or cleared by programs calling your foreign ° d ONLN d≈eq * 2file system with _SetVInfo and you should store it ° d ONLN d˙q}y * between volume mounts. ° d ONLN dÖ `ë í (é `vcbNmFls ° d ONLN dÖ Ãë÷ )l:Set to the number of files in the volume’s root directory. ° d ONLN dUô `• ï (¢ `vcbVBMSt ° d ONLN d^ô Õ )lFFor HFS volumes, this field is used to point to the first block of the ° d ONLN d•• ñ * Fvolume bitmap. Your foreign file system can use this field to point to ° d ONLN dϱ ÃΩ˚ * Can analogous structure. If it doesn’t, the field’s value must be 0. ° d ONLN d0≈ `— ò (Œ ` vcbAllocPtr ° d ONLN d<≈ × )lFFor HFS volumes, this field is used to point to the start block of the ° d ONLN dÉ— Û * Inext allocation search. Your foreign file system can use this field for a ° d ONLN dÕ› ÃÈ⁄ * <similar purpose. If it doesn’t, the field’s value must be 0. ° d ONLN d
Ò `˝ § (˙ ` vcbNmAlBlks ° d ONLN dÒ Ã˝˜ )l=Set to the number of allocation blocks in the volume (maximum ° d ONLN dT˝ à * B$FFFF).This field, together with the vcbAlBlkSiz field, is used to ° d ONLN dó à * Adetermine the number of bytes on a particular volume. It must be ° d ONLN dŸ Ã!Ô * =initialized to a value which when multiplied with vcbAlBlkSiz ° d ONLN d! Ã-« * 7provides a reasonable estimate of the size of the disk. ° d ONLN dO5 `A ú (> ` vcbAlBlkSiz ° d ONLN d[5 ÃA )lJSet to the allocation block size (in bytes). This field, together with the ° d ONLN d¶A ÃM * BvcbNmAlBlks field, is used by the Finder and other applications to ° d ONLN dÈM ÃY * Adetermine the number of bytes on a particular volume. It must be ° d ONLN d+Y Ãeù * -initialized to some non-zero multiple of 512. ° d ONLN dYm `y ë (v ` vcbClpSiz ° d ONLN dcm Ãy
. +H3 Guide to the File System Manager ° d ONLN d W H c y *- vcbAlBlSt ° d ONLN d
W ¥ c˚ )lFSet to the first allocation block in the volume. For HFS volumes, this ° d ONLN d Q c ¥ o * Eis the number of the first block used for files. If your foreign file ° d ONLN d ó o ¥ {È * Dsystem has an analogous structure (that is, if its header blocks are ° d ONLN d ‹ { ¥ á * Kfollowed by a contiguous set of blocks for files), it can use this field in ° d ONLN d( á ¥ ìû * 4the same way. If not, it must leave this field zero. ° d ONLN d] õ H ß à ( § H
vcbNxtCNID ° d ONLN dh õ ¥ ßÛ )lBThe next unused catalog node ID (directory ID or file ID). For HFS ° d ONLN d´ ß ¥ ≥È * Avolumes, this is set to fsUsrCNID when the volume is initialized. ° d ONLN dÌ ≥ ¥ øÛ * BWhen a new directory or file is created, vcbNxtCNID is used as the ° d ONLN d0 ø ¥ À¸ * Fdirectory ID or file ID and then incremented. Your foreign file system ° d ONLN dw À ¥ ◊– * >can use this field for the same purpose, or may leave it zero. ° d ONLN d∂ fl H Î Å ( Ë H
* must be provided. ° d ONLN d“ã Hó É (î H vcbDrvNum ° d ONLN d‹ã ¥óÚ )lBThe drive number of the drive on which the volume is located. This ° d ONLN d ó ¥£› * >field is initialized when the VCB is added to the VCB queue by ° d ONLN d^£ ¥Øfl * 7UTAddNewVCB. When a mounted volume is placed offline or ° d ONLN dñØ ¥ªJ * ejected, vcbDrvNum is set to 0. ° d ONLN d∂√ Hœ ä (à H
vcbDRefNum ° d ONLN d¡√ ¥œ¯ )lDThe driver reference number of the driver used to access the volume. ° d ONLN dœ ¥€ı * CThis field is initialized when the VCB is added to the VCB queue by ° d ONLN dJ€ ¥Áˆ * ;UTAddNewVCB. When a volume is ejected, vcbDRefNum is set to ° d ONLN dÜÁ ¥Ûı * Athe previous value of vcbDrvNum (and hence is a positive number). ° d ONLN d»Û ¥ˇ˜ * BWhen a volume is placed offline, vcbDRefNum is set to the negative ° d ONLN d ˇ ¥ ’ * ;of the previous value of vcbDrvNum (and hence is a negative ° d ONLN dG ¥ ‡ * number). ° d ONLN dP H+ s (( HvcbFSID ° d ONLN dX ¥+È )lEAn identifier for the file system handling the volume; it is zero for ° d ONLN dû+ ¥7fi * ;volumes handled by the File Manager and nonzero for volumes ° d ONLN d⁄7 ¥CÔ * Ehandled by other file systems. Set to your foreign file system’s file ° d ONLN d C ¥O Ë *
system ID. ° d ONLN d +W Hc ä (` H
vcbVRefNum ° d ONLN d 6W ¥c˘ )lCThe volume reference number. This field is initialized when the VCB ° d ONLN d zc ¥oõ * )is added to the VCB queue by UTAddNewVCB. ° d ONLN d §w HÉ u (Ä HvcbMAdr ° d ONLN d ¨w ¥É3 )lUsed internally. Reserved. ° d ONLN d «ã Hó } (î H vcbBufAdr ° d ONLN d —ã ¥ó3 )lUsed internally. Reserved. ° d ONLN d Ïü H´ u (® HvcbMLen ° d ONLN d Ùü ¥´3 )lUsed internally. Reserved. ° d ONLN d
≥ Hø É (º H vcbDirIndex ° d ONLN d
≥ ¥ø3 )lUsed internally. Reserved. ° d ONLN d
6« H” y (– H vcbDirBlk ° d ONLN d
@« ¥”3 )lUsed internally. Reserved. (Ú H3- )
6 )&%Macintosh File System Data Structures ˇ‘ d ˇ ˇˇˇˇ d
d , Times
. ( 3Ä The File System Utility Routines ° d ONLN d U ` a ü ( ^ `
vcbVolBkUp ° d ONLN d U à a )lDSet to the date and time of the last volume backup, specified as the ° d ONLN d P a à mΔ * 2number of seconds since midnight, January 1, 1904. ° d ONLN d É u ` Å £ ( ~ `
* Csave the current value of this field when a volume is unmounted and ° d ONLN dT — à › * Drestore the value when the volume is mounted again to keep a running ° d ONLN dô › à ÈZ * count of writes to the volume. ° d ONLN d∏ Ò ` ˝ ° ( ˙ ` vcbXTClpSiz ° d ONLN dƒ Ò Ã ˝Ã )l6The clump size of the extents overflow file. Reserved. ° d ONLN d˚ ` † ( ` vcbCTClpSiz ° d ONLN d Ãû )l-The clump size of the catalog file. Reserved. ° d ONLN d5 `% ¢ (" ` vcbNmRtDirs ° d ONLN dA Ã% )lHSet to the number of directories in the root directory or leave it zero. ° d ONLN dä- `9 è (6 ` vcbFilCnt ° d ONLN dî- Ã9’ )l:Set to the number of files on the volume or leave it zero. ° d ONLN dœA `M ë (J ` vcbDirCnt ° d ONLN dŸA ÃM )lFSet to the number of directories on the volume (not including the root ° d ONLN d M ÃYF * directory) or leave it zero. ° d ONLN d=a `m ú (j ` vcbFndrInfo ° d ONLN dIa Ãm )lCInformation used by the Finder. For HFS volumes, this field is used ° d ONLN dçm ÃyÎ * >internally by HFS. Leave it all zeroes until set by _SetVInfo. ° d ONLN dÃÅ `ç ï (ä ` vcbVCSize ° d ONLN d÷Å ÃçK )lUsed internally. Reserved. ° d ONLN dÒï `° ¢ (û `
vcbXTAlBks ° d ONLN dHΩ Ã…‚ )l<The size (in blocks) of the extents overflow file. Reserved. ° d ONLN dÖ— `› û (⁄ `
vcbCTAlBks ° d ONLN dê— Ã›¥ )l3The size (in blocks) of the catalog file. Reserved. ° d ONLN dƒÂ `Ò í (Ó `vcbXTRef ° d ONLN dÕ ÃÒ )lBThe path reference number for the extents overflow file. Reserved. ° d ONLN d˘ ` ë ( `vcbCTRef ° d ONLN d˘ ß )l9The path reference number for the catalog file. Reserved. ° d ONLN dS
` ë ( ` vcbCtlBuf ° d ONLN d]
à )l6A pointer to the extents and catalog caches. Reserved. ° d ONLN dî! `- ñ (* ` vcbDirIDM ° d ONLN dû! Ã-˚ )l@The directory last searched. For HFS volumes, this field is used ° d ONLN dfl- Ã9 * Cinternally by HFS to optimize GetCatInfo and GetFInfo. Your foreign ° d ONLN d#9 ÃE * Dfile system can use this field for the same purpose, or may leave it ° d ONLN dhE ÃQ ‰ * zero. ° d ONLN dnY `e ê (b `vcbOffsM ° d ONLN dwY Ãe )lFThe offspring index at the last search. For HFS volumes, this field is ° d ONLN dæe Ãq * @used internally by HFS to optimize GetCatInfo and GetFInfo. Your ° d ONLN dˇq Ã} * Cforeign file system can use this field for the same purpose, or may ° d ONLN dC} Ãâ * leave it zero. ° d ONLN dRõ `߉ (§ `SThere are also three File System Utility routines that let you search the VCB queue ° d ONLN d¶≥ lø p + • ° d ONLN d®≥ yø )
JUTLocateVCBByRefNum searches for the VCB using a working directory number, ° d ONLN dÛø yÀD * (volume reference number, or drive number +º*%Macintosh File System Data Structures )÷3- )
7 ˇÜ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d U T a X + +• ° d ONLN d U a a≤ )
?UTLocateVCBByName searches for the first VCB with a volume name ° d ONLN d B m T y X ( v T• ° d ONLN d D m a yÙ )
LUTLocateNextVCB searches the VCB queue for the next VCB with the volume name ° d ONLN d ë y a Ö˜ * Npassed to UTLocateVCBByName (the Macintosh file system allows multiple mounted ° d ONLN d ‡ Ö a ë * %volumes to have the same volume name) , Helvetica
° d ONLN d £ H ≤0 ( Æ H Maximum Volume and File Sizes
° d ONLN d¿Ê HÚ r (Ô HBoolean ° d ONLN d»Ê ~Ú fi )6Has4GBVols(void) ° d ONLN dŸÚ H˛ N (˚ H{ ° d ONLN d‹˛ Z
Æ + long response; ° d ONLN dÓ Z"t */if (Gestalt(gestaltFSAttr, &response) == noErr) ° d ONLN d " l.‘ + <return ((response & (1L << gestaltFSSupports4GBVols)) != 0); ° d ONLN d^. Z: r (7 Zelse ° d ONLN de: lF Δ + return (false); ° d ONLN duF HR N (O H}
° d ONLN dwe Hq„ * TThe maximum file size supported by the current File Manager programming interface is ° d ONLN dÃq H}˘ * S2 Gigabytes - 1 byte ($7FFFFFFF or 2147483647 decimal) because File Manger Read and ° d ONLN d } Hâb * :Write requests use ioPosOffset as a signed longword value. *l3- )
8 )&%Macintosh File System Data Structures ˇ@ d ˇ ˇˇˇˇ d
d , Times
. ( 3Ä The File System Utility Routines , Helvetica
° d ONLN d U ` d Á ( ` `File Control Blocks d ^ d
° d ONLN d q ` } *^Each time a file is opened on a volume owned by a foreign file system, the foreign file system ° d ONLN d s } ` â * \must read that file’s catalog entry and build a file control block (FCB) in the FCB array. A ° d ONLN d – â ` ïk * 4new FCB is obtained with the UTAllocateFCB function. ° d ONLN d ° ` ≠ *]When a file is closed, the foreign file system must mark the FCB free and release it with the ° d ONLN dc ≠ ` π Ÿ * UTReleaseFCB function. ° d ONLN dz ≈ ` —¥ *IThe structure of a file control block is defined by the FCBRec data type. ,
Courier
° d ONLN dƒ Ê l Ú Δ + !struct FCBRec { ° d ONLN d‘ Ú ä ˛ ÿ +
unsigned long ° d ONLN d‚ Ú ˛ )ffcbFlNm; ° d ONLN dÎ Ú\ ˛ )l /* FCB file number. Non-zero ° d ONLN d
˛n
‘ + marks FCB used */ ° d ONLN d
ä Δ ( ä
SignedByte ° d ONLN d*
& )f fcbFlags; ° d ONLN d4
\∂ )l/* FCB flags */ ° d ONLN dD ä" Δ ( ä
SignedByte ° d ONLN dO ", )f
fcbTypByt; ° d ONLN dZ\"‘ )l/* File type byte */ ° d ONLN do" ä. fi (+ äunsigned short ° d ONLN d~" .& )f fcbSBlk; ° d ONLN dà"\.Ê )l/* File start block (in ° d ONLN d•.n:
unsigned long ° d ONLN dŒ: F )ffcbEOF; ° d ONLN d÷:\F˛ )l/* Logical length or EOF in ° d ONLN d˜FnRû + bytes */ ° d ONLN d R ä^ ÿ ([ ä
unsigned long ° d ONLN dR ^ )ffcbPLen; ° d ONLN dR\^¯ )l/* Physical file length in ° d ONLN d7^njû + bytes */ ° d ONLN d@j äv ÿ (s ä
unsigned long ° d ONLN dNj v )ffcbCrPs; ° d ONLN dWj\v¯ )l/* Current position within ° d ONLN dwvnÇò + file */ ° d ONLN dÇ äé Æ (ã äVCBPtr ° d ONLN dÜÇ é )ffcbVPtr; ° d ONLN dèÇ\é¬ )l/* Pointer to the ° d ONLN d¶énöÊ + corresponding VCB */ ° d ONLN dªö ä¶ ú (£ äPtr ° d ONLN døö ¶& )f fcbBfAdr; ° d ONLN d…ö\¶˛ )l/* File's buffer address */ ° d ONLN d¶ ä≤ fi (Ø äunsigned short ° d ONLN dÙ¶ ≤& )f fcbFlPos; ° d ONLN d˛¶\≤ )l /* Directory block this file ° d ONLN d ≤næû + is in */ ° d ONLN d)æ ä ÿ (« ä
unsigned long ° d ONLN d7æ 8 )f fcbClmpSize; ° d ONLN dDæ\ ‡ )l/* Number of bytes per ° d ONLN d` n÷û + clump */ ° d ONLN di÷ ä‚ ú (fl äPtr ° d ONLN dm÷ ‚2 )f fcbBTCBPtr; ° d ONLN dy÷\‚
)l /* Pointer to B*-Tree control ° d ONLN dú‚nÓÚ + block for this file */ ° d ONLN d≥Ó ä˙ ÿ (˜ ä
unsigned long ° d ONLN d¡Ó ˙> )f
fcbExtRec[3]; ° d ONLN dœÓ\˙¯ )l/* First 3 file extents */ ° d ONLN dÍ˙ ä Æ ( äOSType ° d ONLN dÒ˙ & )f fcbFType; ° d ONLN d˚˙\Ê )l/* File's 4 Finder Type ° d ONLN dnû + bytes */ ° d ONLN d! ä ÿ ( ä
unsigned long ° d ONLN d/ , )f
fcbCatPos; ° d ONLN d:\ ¯ )l/* Catalog hint for use on ° d ONLN dZ n*û + Close */ ° d ONLN dc* ä6 ÿ (3 ä
unsigned long ° d ONLN dq* 6& )f fcbDirID; ° d ONLN d{*\6Ú )l/* Parent Directory ID */ ° d ONLN dï6 äB ® (? äStr31 ° d ONLN dõ6 B& )f fcbCName; ° d ONLN d•6\BÏ )l/* CName of open file */ ° d ONLN dæB äN ñ (K ä}; ° d ONLN d¡N äZ8 * typedef struct FCBRec FCBRec; ° d ONLN dflZ äf& * typedef FCBRec *FCBRecPtr;
° d ONLN d˙É `è Δ (å `Field descriptions ° d ONLN d
. +H3 Guide to the File System Manager ° d ONLN d W H c q *-fcbFlags ° d ONLN d W ¥ c¸ )lIFlags describing the status of the file. Currently the following bits are ° d ONLN d S c ¥ o ⁄ * defined: ° d ONLN d \ o ¥ { ≈ * Bit ° d ONLN d a o2 {b )~Meaning ° d ONLN d i { ¥ á ∫ ( Ñ ¥0 ° d ONLN d k { œ á ) fcbWriteBit ° d ONLN d w {2 á’ )c&Set if data can be written to the file ° d ONLN d û á ¥ ì ∫ ( ê ¥1 ° d ONLN d † á œ ì )fcbResourceBit ° d ONLN d Ø á2 ìÚ )c)Set if this FCB describes a resource fork ° d ONLN d Ÿ ì ¥ ü ∫ ( ú ¥2 ° d ONLN d € ì œ ü) )fcbWriteLockedBit ° d ONLN d Ì ì2 üfl )c'Set if the file has a locked byte range ° d ONLN d ü ¥ ´ ∫ ( ® ¥3 ° d ONLN d ü2 ´^ )~Reserved ° d ONLN d! ´ ¥ ∑ ∫ ( ¥ ¥4 ° d ONLN d# ´ œ ∑' )fcbSharedWriteBit ° d ONLN d5 ´2 ∑æ )c Set if the file has shared write ° d ONLN dY ∑2 √k * permissions ° d ONLN de √ ¥ œ ∫ ( à ¥5 ° d ONLN dg √ œ œ! )fcbFileLockedBit ° d ONLN dx √2 œÌ )c+Set if the file is locked (write-protected) ° d ONLN d§ œ ¥ € ∫ ( ÿ ¥6 ° d ONLN d¶ œ œ €# )fcbOwnClumpBit ° d ONLN dµ œ2 € )c,Set if the file’s clump size is specified in ° d ONLN d €2 ÁZ * the FCB ° d ONLN dÌ Á ¥ Û ∫ ( ¥7 ° d ONLN dÔ Á œ Û )fcbModifiedBit ° d ONLN d˛ Á2 Û¯ )c-Set if the file has changed since it was last ° d ONLN d/ Û2 ˇU * flushed ° d ONLN d7 H o ( HfcbSBlk ° d ONLN d? ¥È )l?Used internally for volumes owned by the Macintosh file system. ° d ONLN d ¥ ‚ * AYour foreign file system can use this field for its own purposes. ° d ONLN d¡' H3 m (0 HfcbEOF ° d ONLN d»' ¥3k )l+Set to the logical end-of-file of the file. ° d ONLN dÙ; HG p (D HfcbPLen ° d ONLN d¸; ¥Gs )l,Set to the physical end-of-file of the file. ° d ONLN d)O H[ o (X HfcbCrPs ° d ONLN d1O ¥[F )l Set to the position of the mark. ° d ONLN dRc Ho m (l HfcbVPtr ° d ONLN dZc ¥o˜ )lESet to point to the volume control block of the volume containing the ° d ONLN d†o ¥{ « * file. ° d ONLN d¶É Hè u (å HfcbBfAdr ° d ONLN dØÉ ¥èÑ )l-Reserved for internal use by the file system. ° d ONLN d›ó H£ s († HfcbFlPos ° d ONLN dÊó ¥£È )l?Used internally for volumes owned by the Macintosh file system. ° d ONLN d&£ ¥Ø‚ * AYour foreign file system can use this field for its own purposes. ° d ONLN dh∑ H√ Ö (¿ H fcbClmpSize ° d ONLN dt∑ ¥√I )l"Set to the clump size of the file. ° d ONLN dóÀ H◊ Ñ (‘ H
PUTLocateFCB lets you find a FCB on a particular volume by file number or by file ° d ONLN d(≈ a— z * name (Ú H3- )
10 )&%Macintosh File System Data Structures ˇ4 d ˇ ˇˇˇˇ d
d , Times
. ( 3Ä The File System Utility Routines ° d ONLN d U l a p ( ^ l• ° d ONLN d U y a )
PUTLocateNextFCB resumes searching for a FCB by file number or file name from the ° d ONLN d S a y mfl * GFCB found by UTLocateFCB (the same file can have multiple access paths) ° d ONLN d õ y l Ö p ( Ç l• ° d ONLN d ù y y Öˆ )
OUTIndexFCB lets you find, one at a time, all of the FCBs on a particular volume ° d ONLN d Ì ë l ù p ( ö l• ° d ONLN d Ô ë y ù‚ )
° d ONLN d} `*M (& ` Working Directory Control Blocks * ^*
° d ONLN dû7 `C
*YWorking directories allow applications that use the old MFS File Manager routines to work ° d ONLN d¯C `O * Xon volumes with directory trees. Working directories allow the use of a volume reference ° d ONLN dQO `[Ú * Rnumber to specify both a volume and a directory on the volume. Each time a working ° d ONLN d§[ `g * \directory is opened on a volume owned by a foreign file system, the foreign file system must ° d ONLN dg `sŒ * Ibuild a working directory control block (WDCB) in the WDCB array with the ° d ONLN dKs ` Á * UTAllocateWDCB function. ° d ONLN ddã `ó
*WWhen a working directory is closed, the foreign file system must mark the WDCB free and ° d ONLN dºó `£ * Urelease it with the UTReleaseWDCB function. When a volume is unmounted and its VCB is ° d ONLN d£ `Ø› * Ldisposed of, UTDisposeVCB closes all working directories open on the volume. ° d ONLN d_ª `« *WThe structure of a working directory control block is defined by the WDCBRec data type. ,
Courier
° d ONLN d∑‹ lË Ã + !struct WDCBRec { ° d ONLN d»Ë äÙ Æ + VCBPtr ° d ONLN dœË Ù& )f wdVCBPtr; ° d ONLN dŸË\ÙÚ )l/* Pointer to VCB of this ° d ONLN d¯Ùn Ê + working directory */ ° d ONLN d
ä ¢ ( älong ° d ONLN d )fwdDirID; ° d ONLN d \ )l /* Directory ID number of this ° d ONLN d? nÊ + working directory */ ° d ONLN dT ä$ ¢ (! älong ° d ONLN dY $, )f
wdCatHint; ° d ONLN dd\$Ï )l/* Hint for finding this ° d ONLN dÇ$n0Ê + working directory */ ° d ONLN dó0 ä< ¢ (9 älong ° d ONLN dú0 <& )f wdProcID; ° d ONLN d¶0\< )l /* Process that created this ° d ONLN d»<nHÊ + working directory */ ° d ONLN d›H äT ñ (Q ä}; ° d ONLN d‡T ä`D * typedef struct WDCBRec WDCBRec; ° d ONLN d ` äl2 * typedef WDCBRec *WDCBRecPtr;
° d ONLN d } `â Δ (Ü `Field descriptions ° d ONLN d0ó `£ ï *wdVCBPtr ° d ONLN d9ó ã )lDA pointer to the VCB of the volume this working directory refers to. ° d ONLN d~´ `∑ ä (¥ `wdDirID ° d ONLN dÜ´ Ã∑ )lFThe directory ID number of the directory this working directory refers ° d ONLN dÕ∑ Ã√ Ÿ * to. +i2%Macintosh File System Data Structures )–3- )
11 ˇé d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d U H a | *+ wdCatHint ° d ONLN d
U ¥ a„ )lBThe Macintosh file system stores a hint so it can quickly find the ° d ONLN d M a ¥ m˛ * Gdirectory the working directory refers to. Your foreign file system can ° d ONLN d ï m ¥ yY * $use this field for its own purposes. ° d ONLN d ∫ Å H ç y ( ä HwdProcID ° d ONLN d √ Å ¥ çª )l3The process ID number passed to the OpenWD request. ° d ONLN d ˜ ü H ´’ ( ® HMThe File System Utility routine UTResolveWDCB lets you search the WDCB array. ° d ONLN dE ´ H ∑ * UUTResolveWDCB lets you find a WDCB by working directory reference number, or lets you ° d ONLN dõ ∑ H √« * Pfind, one at a time, all WDCBs or all of the WDCBs with a particular process ID. ° d ONLN dÏ œ T € s + Note: ° d ONLN dÒ œ s €œ ) J If your foreign file system attempts to allocate a WDCB in response to an ° d ONLN d< € T ÁÊ ( ‰ TJ_OpenWD call and UTAllocateWDCB cannot find a free WDCB in the WDCB array, ° d ONLN dá Á T Û– * Lyou should return the tmfoErr result from UTAllocateWDCB as your result. The ° d ONLN d‘ Û T ˇÂ * TMacintosh file system will then attempt to enlarge the WDCB array and if successful, ° d ONLN d) ˇ T ‘ * Nwill retry the _OpenWD call. Because enlarging the WDCB array will change the ° d ONLN dx T« * Jarray’s location in memory, you should never save the location of WDCBRecs ° d ONLN d√ T#€ * Obetween calls to your foreign file system. A WDCBRecPtr can only be used within ° d ONLN d# T/ * )the context of one file system operation. , Helvetica
° d ONLN d=M H\ È (X HDrive Queue Elements \ F\
° d ONLN dRi HuÚ *\The File Manager maintains a list of all disk drives connected to the computer. It maintains ° d ONLN dØu HŘ * \this list in the drive queue, which is a standard Operating System queue. The drive queue is ° d ONLN d Å Hçˇ * `initially created at system startup time. Elements are added to the queue at system startup time ° d ONLN dmç Hô˝ * Zor when the AddDrive function is called. The drive queue can support any number of drives, ° d ONLN d»ô H•Û * Xlimited only by memory space. Each element in the drive queue contains information about ° d ONLN d!• H±¸ * ]the corresponding drive; the structure of a drive queue element is defined by the DrvQEl data ° d ONLN d± HΩ ` * type. ° d ONLN dÖ… H’Û *ZGiven a drive number, the UTFindDrive File System Utility routine will return a pointer to ° d ONLN d‡’ H·Ç * Ethe associated drive queue element if it is found in the drive queue. ,
Courier
° d ONLN d&ˆ T Æ + !struct DrvQEl { ° d ONLN d6 r ¢ + QElemPtr ° d ONLN d? ÿ ¸ )fqLink; ° d ONLN dFD» )l/* Next queue entry */ ° d ONLN d] r ê ( rshort ° d ONLN dc ÿ ¸ )fqType; ° d ONLN djDŒ )l/* Flag for dQDrvSz and ° d ONLN dáV&ò + dQDrvSz2 */ ° d ONLN dì& r2 ê (/ rshort ° d ONLN dô& ÿ2 )fdQDrive; ° d ONLN d¢&D2∞ )l/* Drive number */ ° d ONLN dµ2 r> ñ (; rshort ° d ONLN dº2 ÿ> )f dQRefNum; ° d ONLN dΔ2D>Ú )l /* Driver reference number */ ° d ONLN d‰> rJ ê (G rshort ° d ONLN dÍ> ÿJ )fdQFSID; ° d ONLN dÚ>DJº )l/* File system ID */ ° d ONLN dJ rV Δ (S runsigned short ° d ONLN dJ ÿV )fdQDrvSz; ° d ONLN d JDV¯ )l /* Number of logical blocks on ° d ONLN dCVVbÜ + drive */ ° d ONLN dLb rn Δ (k runsigned short ° d ONLN d[b ÿn )f dQDrvSz2; ° d ONLN debDnÚ )l /* Additional field for large ° d ONLN dànVzå + drives */ ° d ONLN díz rÜ ~ (É r}; ° d ONLN dïÜ rí * typedef struct DrvQEl DrvQEl; ° d ONLN d≥í rû * typedef DrvQEl *DrvQElPtr;
(Ú H3- )
12 )&%Macintosh File System Data Structures ˇ d ˇ ˇˇˇˇ d
d , Times
. ( 3Ä The File System Utility Routines ° d ONLN d U ` a Δ ( ^ `Field descriptions ° d ONLN d o ` { | *qLink ° d ONLN d o à {
)lIA pointer to the next entry in the drive queue. This field is initialized ° d ONLN d c { Ã á› * 8when the drive is added to the drive queue by _AddDrive. ° d ONLN d ú è ` õ ~ ( ò `qType ° d ONLN d ¢ è Ã õ
)lFThe queue type. Used to specify the size of the drive. If the value of ° d ONLN d È õ Ã ß
* EqType is 0, the number of logical blocks on the drive is contained in ° d ONLN d/ ß Ã ≥ * Ethe dQDrvSz field alone. If the value of qType is 1, both dQDrvSz and ° d ONLN du ≥ à øÛ * >dQDrvSz2 are used to store the number of blocks; in that case, ° d ONLN d¥ ø à À * @dQDrvSz2 contains the high-order word of this number and dQDrvSz ° d ONLN dı À à ◊V * contains the low-order word. ° d ONLN d fl ` Î à ( Ë `dQDrive ° d ONLN d fl à Π)lGThe drive number of the drive. This field is initialized when the drive ° d ONLN db Î Ã ˜î * )is added to the drive queue by _AddDrive. ° d ONLN då ˇ ` ó ( `dQRefNum ° d ONLN dï ˇ à )lCThe driver reference number of the driver controlling the device on ° d ONLN dŸ à * Hwhich the volume is mounted. This field is initialized when the drive is ° d ONLN d" Ã#â * &added to the drive queue by _AddDrive. ° d ONLN dI+ `7 à (4 `dQFSID ° d ONLN dP+ Ã7 )lIAn identifier for the file system handling the volume in the drive; it is ° d ONLN dö7 ÃCÛ * <zero for volumes handled by the File Manager and nonzero for ° d ONLN d◊C ÃOÖ * &volumes handled by other file systems. ° d ONLN d˛W `c å (` `dQDrvSz ° d ONLN dW Ãcï )l*The number of logical blocks on the drive. ° d ONLN d1k `w í (t `dQDrvSz2 ° d ONLN d:k Ãw )lJAn additional field to handle large drives. This field is used only if the ° d ONLN dÖw ÃÉ * =qType field contains 1 and then, contains the high-order word ° d ONLN d√É Ãè≈ * 5specifying the number of logical blocks on the drive. ,
Zapf Dingbats
° d ONLN d˘° l≠ w (´ ls ° d ONLN d˚¢ ~Æ ≤ )Warning: ° d ONLN d¢ ≤Æ˘ )4B If the device driver whose reference number is dQRefNum supports ° d ONLN dFÆ ~∫˝ (∑ ~Sthe Return Format List _Status call (csCode = 6), the volSize field in the returned ° d ONLN dö∫ ~Δ˚ * MFormatListRec with the diCIFmtFlagsCurrentBit set should be used to determine ° d ONLN dËΔ ~“ * Nthe number of blocks instead of the dQDrvSz and dQDrvSz2 fields in the DrvQEl. ° d ONLN d7“ ~fi˘ * ODrivers that support Return Format List (for example, the .Sony driver) may not ° d ONLN dáfi ~Í˙ * Lsupport the dQDrvSz and dQDrvSz2 fields or may use them for other purposes.
° d ONLN d”‡˙È (Á˙s
° d ONLN d’¸ ` ( `[There are also four flag bytes preceding each drive queue element. The four flag bytes must ° d ONLN d1 ` * \be allocated by the disk driver at the same time the drive queue element is allocated. These ° d ONLN dé ` * (bytes contain the following information: ° d ONLN d∑8 lD Ü + $Byte ° d ONLN dº8 ñD » )*Contents ° d ONLN d≈P l\ r (Y l0 ° d ONLN d«P ñ\c )*,Bit 7=1 if the volume on the drive is locked ° d ONLN dÙ\ lh r (e l1 ° d ONLN dˆ\ ñhÒ )*P0 if no disk in drive; 1 or 2 if disk in drive; 8 if nonejectable disk in drive; ° d ONLN dIh ñt˙ * L$FC–$FF if disk was ejected within last 1.5 seconds; $48 if disk in drive is ° d ONLN dòt ñÄ; * $nonejectable but driver wants a call ° d ONLN dΩÄ lå r (â l2 ° d ONLN døÄ ñåG )*%Used internally during system startup ° d ONLN dÂå lò r (ï l3 ° d ONLN dÁå ñò" )* Bit 7=0 if disk is single-sided ° d ONLN d ∞ `º˘ (π `VYou can read these flags by subtracting 4 from the beginning of a drive queue element. +’9%Macintosh File System Data Structures )–3- )
14 )&%Macintosh File System Data Structures ˇ8 d ˇ ˇˇˇˇ d
d , Times
. ( 3Ä The File System Utility Routines , Helvetica
° d ONLN d s ` Çã ( ~ ` FILE SYSTEM LOCATION INFORMATION l ^ l Ö ^ Ö
° d ONLN d ! ú ` ®˚ *'XA file system must be able to determine the file, directory, or volume using information ° d ONLN d z ® ` ¥ * `passed to it in a parameter block. This section tells how to use File System Utility routines to ° d ONLN d € ¥ ` ¿
* [make that determination. The section titled “HFS Specifications” in Inside Macintosh: Files ° d ONLN d7 ¿ ` Ãp * =lists the various ways files or directories can be specified.
° d ONLN du ‰ ` ÛX *& About Volume Reference Numbers Û ^ Û
° d ONLN dî `
*TEach volume is given a unique volume reference number when the volume is mounted and ° d ONLN dÈ ` * Mthe volume’s VCB is added to the VCB queue by UTAddNewVCB. A volume reference ° d ONLN d7 `$ * Ynumber is only valid for a particular volume while that volume is mounted. If a volume is ° d ONLN dë$ `0 * Wunmounted and then mounted again, a new volume reference number will be assigned to the ° d ONLN dÈ0 `< á * volume.
° d ONLN dÒT `c) *&About Directory ID Numbers c ^c
° d ONLN d p `|˛ *ZA foreign file system must be able to assign a directory ID number to all directories on a ° d ONLN dg| `à * Yvolume. Each directory ID must be unique and cannot be used as a file number for the same ° d ONLN d¡à `î * ^volume. For directories other than the root directory (which must be fsRtDirID), the directory ° d ONLN d î `† * %ID must be fsUsrCNID (16) or greater. ° d ONLN dF¨ `∏ *YWhile a volume is mounted, directory IDs must remain the same. Directory IDs must be kept ° d ONLN d†∏ `ƒ˛ * Rthe same while a volume is unmounted. Macintosh programs and the Alias Manager use ° d ONLN dÛƒ `–º * Hdirectory IDs to locate directories on the volume between volume mounts.
° d ONLN d<Ë `˜ Ó *&About File Numbers ˜ ^˜
° d ONLN dO `˛ *[A foreign file system must be able to assign a file number to all files on a volume. A file ° d ONLN d´ ` * Xnumber is never passed as a parameter to a file system routine. Each file number must be ° d ONLN d `( * Yunique and cannot be used as a directory ID number for the same volume. File numbers for ° d ONLN d^( `4 * Wfiles opened by programs using File Manager requests must be fsUsrCNID (16) or greater. ° d ONLN d∂4 `@ * \File numbers less than fsUsrCNID are reserved for the root directory ID and for files opened ° d ONLN d@ `L * _by file systems for their own internal use (for example, the catalog and extents overflow files ° d ONLN dsL `X * Wused by the HFS file system). The File Manager’s UnmountVol code returns fBsyErr to the ° d ONLN dÀX `d * acaller and will not call your foreign file system if there are open files on the specified volume ° d ONLN d-d `p¸ * Xwith file numbers fsUsrCNID or greater. If your foreign file system open files with file ° d ONLN dÜp `| * \numbers less than fsUsrCNID, your foreign file system is responsible for closing those files ° d ONLN d„| `à Ï * before unmounting a volume. ° d ONLN dˇî `†
*XWhile a volume is mounted, file numbers must remain the same. File numbers should, if at ° d ONLN d X† `¨| * ;all possible, be kept the same while a volume is unmounted. +ÌI File System Location Information )∏3- )
15 ˇ¥ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d U H aÒ *+]A foreign file system will use a file number in the file control block (FCB) of an open file. ° d ONLN d ^ a H mÚ * [The file number can be used to find a FCB, and is used to identify multiple access paths to ° d ONLN d ∫ m H yÓ * Tthe same file by the UTAdjustEOF and UTCheckPermission File System Utility routines. , Helvetica
° d ONLN d ë H † ¸ *&About File ID References † F †
° d ONLN d( ≠ H πı *]File ID references are an optional file system feature that allow the Alias Manager and other ° d ONLN dÜ π H ≈ * Zprograms to track files that have been moved or renamed within a volume. If a foreign file ° d ONLN d· ≈ H —Î * Zsystem supports file ID references on its volumes, the foreign file system must be able to ° d ONLN d< — H ›˛ * cassign a file ID reference to a file, and later return that file’s location and name given only the ° d ONLN d† › H Èê * Efile ID reference number, even if the file has been moved or renamed. ° d ONLN dÊ ı HÙ *VFile ID reference numbers must be kept the same while a volume is unmounted. Macintosh ° d ONLN d= H
ˆ * Zprograms and the Alias Manager use file ID reference numbers to locate files on the volume ° d ONLN dò
H ø * between volume mounts.
° d ONLN dØ1 H@ ı *&Determining the Volume @ F@
° d ONLN dΔM HYˇ *]Before a foreign file system is called, the Macintosh file system and the File System Manager ° d ONLN d$Y He˛ * \have determined what volume is the target of the call and what file system owns that volume. ° d ONLN dÅe Hqÿ * UThe volume is identified by the volume control block parameter passed to foreign file ° d ONLN d◊q H}Ô * Ssystem’s HFSCIProc. UTDetermineVol can also be used to determine what volume is the ° d ONLN d+} Hâ é * target of a call. ° d ONLN d=ï H°‡ *OTwo file system calls are exceptions: _MountVol and _VolumeMount. _MountVol and ° d ONLN dç° H≠˘ * T_VolumeMount both deal with unmounted volumes (or potentially unmounted volumes), so ° d ONLN d‚≠ HπÒ * Wthe volume control block parameter passed to foreign file system’s HFSCIProc is unused.
° d ONLN d;— H‡u *&*Determining the File or Directory Location ‡ F‡
° d ONLN dfÌ H˘ˇ *`A file’s location can be given in a file system call by full pathname, or by partial pathname. A ° d ONLN d«˘ H„ * Xdirectory’s location can be given by full pathname, partial pathname, or directory ID. A ° d ONLN d H” * Uforeign file system must determine the directory ID the pathname starts in before the ° d ONLN dv H ˚ * [pathname to a file or directory can be parsed. Listing 3-2, GetCurrentDir, shows how to use ° d ONLN d“ H)Ô * \the contents of the call’s parameter block and File System Utility routines to determine the ° d ONLN d/) H5ˆ * [directory parsing should begin in. The dirID input parameter contains the directory ID from ° d ONLN dã5 HAÓ * _the parameter block if that field is valid for the request recieved. Not all requests include a ° d ONLN dÎA HM˚ * ]directory ID specification. For example, the old file system calls like PBOpen do not include ° d ONLN d IM HY’ * Ta directory ID specification. GetCurrentDir returns a pointer to the volume’s VCB in ° d ONLN d ûY He * ZvolCtrlBlockPtr, the directory where parsing should begin is returned in currentDirectory, ° d ONLN d ˘e HqÄ * Band the method used to determine the volume is returned in status. ° d ONLN d
<} ââ Õ +A Listing 3-2. ° d ONLN d
H} Õâ¿ )D2 Determining where directory parsing should start ,
Courier
° d ONLN d
{í Hû f (õ HOSErr ° d ONLN d
Åí lûÚ )$AGetCurrentDir(ParmBlkPtr pb, long dirID, VCBPtr *volCtrlBlockPtr, ° d ONLN d
û Δ™™ +Z &long *currentDirectory, short *status) ° d ONLN d
Ò™ H∂ N (≥ H{ ° d ONLN d
Ù∂ Z¬ x + OSErr ° d ONLN d
¸∂ ¢¬ à )Hresult; ° d ONLN d ¬ ZŒ x (À Zshort ° d ONLN d
¬ ¢Œ Í )H moreMatches;
(Ú H3- )
16 )& File System Location Information ˇ d ˇ ˇˇˇˇ d
d , Times
. ( 3Ä The File System Utility Routines ,
Courier
° d ONLN d U r a ê ( ^ rshort ° d ONLN d U ∫ a Í )HvRefNum; ° d ONLN d a r m Æ ( j r
 ® Ò‡ + 4/* Current directory is always the root directory */ ° d ONLN dC Ò ® ˝\ * *currentDirectory = fsRtDirID; ° d ONLN df ˝ ® à * break; ° d ONLN dt ñ!Œ ( ñ4/* Determined by volume refNum or by drive number */ ° d ONLN d¨! ñ- ¸ * case dtmvVRefNum: ° d ONLN d¡- ñ9 * case dtmvDriveNum: ° d ONLN dÿ9 ®Eº + ./* Current directory is dirID if specified; */ ° d ONLN d E ®Qò * (/* otherwise, it's the root directory */ ° d ONLN d8Q ®] * if (dirID != 0) ° d ONLN dM] ∫iV + *currentDirectory = dirID; ° d ONLN dli ®u ¿ (r ®else ° d ONLN dvu ∫Ån + *currentDirectory = fsRtDirID; ° d ONLN dôÅ ®ç à (ä ®break; ° d ONLN dßô ñ•û (¢ ñ,/* Determined by working directory refNum */ ° d ONLN d◊• ñ± * case dtmvWDRefNum: ° d ONLN dÓ± ®Ωº + ./* Current directory is dirID if specified; */ ° d ONLN d!Ω ®…û * )/* otherwise, it's wdDirID in the WDCB */ ° d ONLN dO… ®’ * if (dirID != 0) ° d ONLN dd’ ∫·V + *currentDirectory = dirID; ° d ONLN dÉ· ®Ì ¿ (Í ®else ° d ONLN dåÌ ®˘ Æ * { ° d ONLN dì˘ ∫¯ + 5result = UTResolveWDCB(0, 0, pb->fileParam.ioVRefNum, ° d ONLN d◊J∞ +ê &wdCtrlBlockPtr); ° d ONLN dÓ ∫ 2 ( ∫if (result == noErr) ° d ONLN d Ã)‘ + ,*currentDirectory = wdCtrlBlockPtr->wdDirID; ° d ONLN d:) ®5 Æ (2 ®} ° d ONLN d@5 ®A à * break; ° d ONLN dNM ñYb (V ñ"/* Determined by default volume */ ° d ONLN dtY ñe ¸ * case dtmvDefault: ° d ONLN däe ®qº + ./* Current directory is dirID if specified; */ ° d ONLN dΩq ®}™ * +/* otherwise, it's the default directory */ ° d ONLN dÌ} ®â * if (dirID != 0) ° d ONLN dâ ∫ïV + *currentDirectory = dirID; ° d ONLN d!ï ®° ¿ (û ®else ° d ONLN d*° ®≠ Æ * { ° d ONLN d1≠ ∫π⁄ + 0wdpb.ioNamePtr = NULL; /* the name not needed */ ° d ONLN dgπ ∫≈z * result = UTGetDefaultVol(&wdpb); ° d ONLN dç≈ ∫—2 * if (result == noErr)
° d ONLN d ¨ ¯ HÛ * YOnce the directory ID where parsing will begin has been determined, the pathname (if any) ° d ONLN d Hˆ * \must be parsed to find the object. The process of parsing a pathname consists of getting the ° d ONLN dc H ˙ * Wnext component in a pathname and determining where that component is on the volume, and ° d ONLN dª H(˝ * ^then repeating those two steps until the end of the pathname is reached. Parsing can go either ° d ONLN d( H4˝ * ]up or down in a volume’s directory heirarchy so a foreign file system must be able to find an ° d ONLN dx4 H@˜ * Zobject by name within a specified directory to move down in the heirarchy and must be able ° d ONLN d”@ HLÔ * Zto find an object’s parent directory to move up in the heirarchy. Listing 3-3 shows how to ° d ONLN d.L HXÔ * Zparse a pathname. How a foreign file system finds an object on a volume is specific to the ° d ONLN dâX Hd § * foreign file system. ° d ONLN dûp œ| +á Listing 3-3. ° d ONLN d™p|{ )D Parsing a pathname
objectNumber; ° d ONLN d–¡ ÍÕÏ )Z+/* directory ID or file number of object */ ° d ONLN d¸Õ HŸ T (÷ H}; ° d ONLN dˇŸ HÂJ * +typedef struct ObjectInfoRec ObjectInfoRec; ° d ONLN d+ HÒ8 * (typedef ObjectInfoRec *ObjectInfoRecPtr; ° d ONLN dU˝ H Í *OSErr ParsePathName (VCBPtr ° d ONLN dq˝ ¸ ∞ )¥ theVCB, long currentDirectory, ° d ONLN dò Δ‡ ( Δ/StringPtr namePtr, ObjectInfoRecPtr objectInfo) ° d ONLN d» H! N ( H{ ° d ONLN dÀ! Z- x + OSErr ° d ONLN d”! ¢- à )Hresult; ° d ONLN d‹- Z9 ¢ (6 Z ParsePathRec ° d ONLN dÈ- ¥9 Í )Z parseRec; ° d ONLN dÙ9 ZE x (B ZStr31 ° d ONLN d¸9 ¢E ˆ )HlastComponent; ° d ONLN dQ Z]¬ (Z Z</* init parseRec to start parsing at beginning of namePtr */ ° d ONLN dL] Zi ¸ * parseRec.namePtr = namePtr; ° d ONLN dii Zu * parseRec.startOffset = 0; ° d ONLN dÑu ZÅ * parseRec.ComponentLength = 0; ° d ONLN d£Å Zç ˆ * parseRec.moreName = false; ° d ONLN døç Zô * parseRec.foundDelimiter = false;
(Ú H3- )
18 )& File System Location Information ˇ& d ˇ ˇˇˇˇ d
d , Times
. ( 3Ä The File System Utility Routines ,
Courier
° d ONLN d U r a˛ ( ^ rB/* Get the length of the volume name (if any) and use it to adjust ° d ONLN d E a r m * E** the startOffset to point to the beginning of the partial pathname. ° d ONLN d ç m r y
* D** UTParsePathname also ensures the pathname is not NULL or an empty ° d ONLN d ‘ y r Ö Æ *
µ ∫ ¡ Δ * */ ° d ONLN d ¡ ∫ ÕP * objectInfo->isDir = true; ° d ONLN d4 Õ ∫ Ÿ¬ * ,objectInfo->objectNumber = currentDirectory; ° d ONLN df Ÿ ∫ Â⁄ * 0/* Call foreign file system specific code to get ° d ONLN dù  ∫ Òz * ** information on this directory ° d ONLN dƒ Ò ∫ ˝ Δ * */ ° d ONLN dà ˝ ∫ º * +result = FFSGetDirInfo(theVCB, objectInfo); ° d ONLN d¸ ® Æ ( ®} ° d ONLN d ®! ¿ * else ° d ONLN d ! ®- Æ * { ° d ONLN d- ∫9
+ 8/* The pathname ended with 'name:' or 'name', so name is ° d ONLN dQ9 ∫E * ** the object. ° d ONLN dfE ∫Q Δ * */ ° d ONLN dnQ ∫]Ú * 4objectInfo->localName[0] = parseRec.ComponentLength; ° d ONLN d®] ∫i™ * (BlockMove((Ptr)((long)parseRec.namePtr + ° d ONLN dŸi fiuz +$ parseRec.startOffset + 1), ° d ONLN d˙u ÃÅt (~ à &(objectInfo->localName[1]), ° d ONLN d Å Ãçh * parseRec.ComponentLength); ° d ONLN d?ô ∫•º (¢ ∫+objectInfo->parentDirID = currentDirectory; ° d ONLN dp• ∫±⁄ * 0/* Call foreign file system specific code to get ° d ONLN dß± ∫Ω\ * ** information on this file ° d ONLN d…Ω ∫… Δ * */ ° d ONLN d—… ∫’™ * (result = FFSGetFile(theVCB, objectInfo); ° d ONLN d˛’ ®· Æ (fi ®} ° d ONLN d· ñÌ ú (Í ñ} ° d ONLN dÌ Ñ˘ ä (ˆ Ñ} ° d ONLN d
˘ r x ( r} ° d ONLN d
r ä * else ° d ONLN d r x * { ° d ONLN d Ñ) + result = bdNamErr; ° d ONLN d* )
)~,/* Default to bad name (if ioNamePtr != NULL ° d ONLN da)5¯ * )** or ioNamePtr doesn't point to an empty ° d ONLN dï5A
* ,** string). Otherwise, the code that follows ° d ONLN dÃAMº * ** will set up the real result. ° d ONLN dˆMY * */ ° d ONLN d˚Y ÑeÜ (b Ñ+if ((namePtr == NULL) || (namePtr[0] == 0)) ° d ONLN d)e Ñq ä * { ° d ONLN d.q ñ}¯ + ;/* pathname was NULL or a zero length string, so we found a ° d ONLN dn} ñât * %** directory at the end of the string ° d ONLN dòâ ñï ¢ * */ ° d ONLN dûï ñ°, * objectInfo->isDir = true; ° d ONLN dª° ñ≠û * ,objectInfo->objectNumber = currentDirectory; ° d ONLN dÎ≠ ñπ * ?/* Call foreign file system specific code to get information on ° d ONLN d/π ñ≈ ¸ * ** this directory ° d ONLN dE≈ ñ— ¢ * */
+∑$ File System Location Information )∏3- )
21 ˇ† d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ,
Courier
° d ONLN d U ~ aÄ +6++result = FFSGetDirInfo(theVCB, objectInfo); ° d ONLN d . a l m r ( j l} ° d ONLN d 1 m Z y ` ( v Z} ° d ONLN d 4 y Z Ö ∫ * return (result); ° d ONLN d E Ö H ë N ( é H}
(Ú H3- )
22 )& File System Location Information ˇ
N d ˇ ˇˇˇˇ d
d , Times
. ( 3Ä The File System Utility Routines , Helvetica
° d ONLN d s ` Ç^ ( ~ `THE MACINTOSH VOLUME CACHE l ^ l Ö ^ Ö
° d ONLN d ú ` ® *'ZThe Macintosh operating system uses a volume (disk) cache for input and output operations. ° d ONLN d v ® ` ¥È * RThe following sections provide both general information about caching and specific ° d ONLN d … ¥ ` ¿Ã * Jinformation about the volume cache used by the Macintosh operating system.
° d ONLN d ÿ ` Á_ *& About the Macintosh Volume Cache Á ^ Á
° d ONLN d5 Ù ` *UThe Macintosh operating system allows users to set aside memory for a general-purpose ° d ONLN dã ` * Xvolume cache. A volume cache is an area in memory that is used to store blocks that have ° d ONLN d‰ ` * [been recently read from or written to a volume. By keeping blocks in memory that are likely ° d ONLN d@ `$
* ]to be read or written again, a file system can avoid repeating I/O operations to the volume’s ° d ONLN dû$ `0 * adevice and, as a result, can save a great deal of time. Use of the cache can greatly increase the ° d ONLN d 0 `< * Zspeed of many applications. The one disadvantage is that memory set aside for the cache is ° d ONLN d[< `H ‡ * unavailable to applications.
° d ONLN dxZ `i3 * How Users Control the Cache
° d ONLN dît `Ä *VThe Memory control panel allows users to change the amount of memory set aside for the ° d ONLN dÎÄ `å * Xcache. The Memory control panel allows users to reclaim some, but not all, of the memory ° d ONLN dDå `ò * !used by the cache when necessary. ° d ONLN df§ `∞ *_Although a foreign file system cannot determine the size of the cache, there is always at least ° d ONLN dΔ∞ `º „ * 32K set aside for the cache.
° d ONLN d„Œ `›i * "The Cache and Foreign File Systems
° d ONLN dË `Ù *^A foreign file system can gain access to the cache by using the cache routines provided by the ° d ONLN deÙ ` ‰ * SFile System Manager. Foreign file system’s should try to use these routines for all ° d ONLN dπ ` * [input/output operations. There are a number of reasons why a foreign file system should use ° d ONLN d `x * ?the cache routines instead of calling a device driver directly: ° d ONLN dU$ l0 p + • ° d ONLN dW$ y0
)
TIncreased throughput: By reducing the number of input/output operations, use of the ° d ONLN d¨0 y<F * +cache can dramatically increase throughput. ° d ONLN dÿH lT p (Q l• ° d ONLN d⁄H yT )
WUsers can control the cache: The Control Panel lets users control the amount of memory ° d ONLN d2T y` › * set aside for caching. ° d ONLN dIl lx p (u l• ° d ONLN dKl yx )
YEasier implementation: The foreign file system does not have to allocate a buffer for an ° d ONLN d•x yÑã * <entire block when only part of a block is to be transferred. ° d ONLN d‚ê lú p (ô l• ° d ONLN d‰ê yúÚ )
OSupport for both logical and physical blocks: The Macintosh cache routines can ° d ONLN d4ú y® * Vperform operations involving physical blocks on a volume or logical blocks for a file. +ÂMThe Macintosh Volume Cache )ß3- )
23 ˇJ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d a T m X + 7• ° d ONLN d a a m )
° d ONLN d  T Ò _ ( Ô Ts ° d ONLN d Ê f Ú ö )Warning: ° d ONLN d Ê ö Ú‡ )4I It is important to note the use of the cache routines is the only way a ° d ONLN db Ú f ˛„ ( ˚ fRforeign file system can perform asynchronous I/O. If a foreign file system calls a ° d ONLN dµ ˛ f
fl * Rdevice driver directly, all I/O operations are executed synchronously, even if the ° d ONLN d
f„ * Rcalling application has requested asynchronous I/O. If your foreign file system is ° d ONLN d[ f"Ë * Vcalled at interrupt time and the device driver (or another device driver called by the ° d ONLN d≤" f.º * Ldevice driver) is busy, calling the device driver directly will deadlock the ° d ONLN dˇ. f:œ * MMacintosh system. For this reason, all calls to most device drivers should be ° d ONLN dM: fF * !made through the cache routines.
Reserved ° d ONLN d±‰ ïÎ )4J cache blocks - A cache block that is in use is reserved. A reserved cache ° d ONLN d¸ a¸˙ (˘ aYblock corresponds to a logical block of a file or a physical block of a volume and is not ° d ONLN dV¸ aÿ * Navailable for reuse. A cache block is reserved with the UTGetBlock function. A ° d ONLN d• aÛ * Zreserved cache block can contain clean or dirty data (or no valid data at all if the cache ° d ONLN d a Ë * Rblock was obtained for use as a write buffer). Cache blocks should not be reserved ° d ONLN d S a, Ó * between calls to a file system. ° d ONLN d s8 TD X (A T• ° d ONLN d u8 aD ì )
Released ° d ONLN d }8 ìD˚ )2O cache blocks - A cache block that is very likley to be needed again but is not ° d ONLN d ÕD aPı (M aWreserved should be released. A released cache block still corresponds to a block of the ° d ONLN d
%P a\Ô * Wfile or volume, but is available for reuse. A released cache block can contain clean or ° d ONLN d
}\ ah ë * dirty data. ° d ONLN d
ât TÄ X (} T• ° d ONLN d
ãt aÄ z )
Free ° d ONLN d
èt zÄÙ )Q cache blocks - A cache block that isn’t likley to be used again should be marked ° d ONLN d
·Ä aåŒ (â aSfree. A free cache block still contains valid data and is still associated with the ° d ONLN d 5å aò‚ * Qcorresponding block of the volume, but not with a file on the volume. Dirty cache ° d ONLN d áò a§Ò * Sblocks should be flushed before marking them free. Free cache blocks will be reused ° d ONLN d €§ a∞ Î * before released cache blocks. (Ú H3- )
24 )&The Macintosh Volume Cache ˇJ d ˇ ˇˇˇˇ d
d , Times
. ( 3Ä The File System Utility Routines ° d ONLN d a l m p ( j l• ° d ONLN d a y m ¶ )
* $volume, a dirty cache block must be ° d ONLN dÈ µ
¡7 )≠flushed ° d ONLN d µ7 ¡ )*1 by writing its contents out to the volume. This ° d ONLN d" ¡ ` Õ Ï ( ` occurs in the following cases: ° d ONLN dA Ÿ l  p + • ° d ONLN dC Ÿ y ² )
SThe Macintosh operating system replaces a released cache block that is dirty with a ° d ONLN dó Â y Ò * Tblock from the volume that is being read into the cache. When this occurs, the dirty ° d ONLN dÏ Ò y ˝D * -cache block is flushed before it is replaced. ° d ONLN d l p ( l• ° d ONLN d yˆ )
RThe foreign file system flushes the dirty cache block in response to a _FlushFile, ° d ONLN do y! ˜ * _Close, or _FlushVol call. ° d ONLN dä- l9 p (6 l• ° d ONLN då- y9 )
SThe foreign file system flushes a cache block at some other time (for example, when ° d ONLN d‡9 yE Ë * handling a _Write call). ° d ONLN d˘Q `] (Z `WWhen using the cache routines, remember that any cache operation may force a previously ° d ONLN dQ] `i * [cached block to be removed from memory. If there are no trashed or free cache blocks, a new ° d ONLN d≠i `u * ]block that is read into the cache from the volume replaces the contents of the least recently ° d ONLN d u `ÅC * 2used of the released blocks (if any) in the cache. , Helvetica
° d ONLN d>ì `¢S * !Logical to Physical Block Mapping
° d ONLN d`≠ `π˝ *ZThe Macintosh cache routines can read or write either logical blocks of a file or physical ° d ONLN dªπ `≈ * [blocks of a volume. However, because disk driver device calls always read or write physical ° d ONLN d≈ `— * ^blocks of a volume, a foreign file system must provide a routine to map logical file blocks to ° d ONLN dv— `› * \physical volume blocks called the logical to physical routine. The address of the logical to ° d ONLN d”› `È * [physical routine is passed to the File System Manager in the foreign file system’s HFSCIRec ° d ONLN d/È `ı * ^and as a parameter to some cache routines. The interface for the logical to physical routine a ° d ONLN déı ` * UFSM-based foreign file system must supply is defined in “The HFS Component Interface” ° d ONLN d‰ `
Ü * chapter. ° d ONLN dÌ `% *bIt is the responsibility of the foreign file system to return an eofErr when a request for data is ° d ONLN dP% `1 * cbeyond the current logical end of file. It is the responsibility of the logical to physical routine ° d ONLN d¥1 `= * Xto return an eofErr error when a cache routine asks for block mapping beyond the current ° d ONLN d
= `I æ * physical end of file. +˛¨The Macintosh Volume Cache )ß3- )
25 ˇ h d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager , Helvetica
° d ONLN d s H ÇA *L FILE SYSTEM UTILITY ROUTINES l F l Ö F Ö ° d ONLN d ® H ∑ ∂ *5
UTAllocateFCB ∑ F ∑å
° d ONLN d + ƒ H – *YUse the UTAllocateFCB function to allocate a FCBRec in the FCB array when opening a file. ,
Courier
° d ONLN d Ö › H ÈV *-pascal OSErr UTAllocateFCB(short *fileRefNum, ° d ONLN d ª È ˝ ı´ +µ FCBRecPtr *fileCtrlBlockPtr);
° d ONLN d Ÿ H Ä ( H
fileRefNum ° d ONLN d ‰ ¥ ˛ )lFContains a pointer to a short. UTAllocateFCB places the file reference ° d ONLN d+ ¥„ * Anumber of the allocated FCBRec into the field referred to by this ° d ONLN dm ¥$ Ê *
parameter. ° d ONLN dx, H8 ì (5 HfileCtrlBlockPtr ° d ONLN dâ, ¥8¯ )lAContains a pointer to a FCBRecPtr. UTAllocateFCB places a pointer ° d ONLN dÀ8 ¥D * Eto the allocated FCBRec into the field referred to by this parameter. ° d ONLN dV Hb˝ (_ HYIf an FCBRec can be allocated in the FCB array, the FCB will be marked in use (fcbFlNm is ° d ONLN dkb Hn„ * Zset to -1), the file reference number will be returned in fileRefNum, and a pointer to the ° d ONLN dΔn Hz * ^allocated FCBRec will be returned in fileCtrlBlockPtr. The allocated FCBRec is not initialized ° d ONLN d%z HÜ“ * Xin any way. It is up to your foreign file system to initialize all fields in the FCBRec. ° d ONLN d~í Hû„ *VIf an FCB cannot be allocated because there are no FCBRecs left in the FCB array, this ° d ONLN d’û H™ ◊ * function will return a tmfoErr. ° d ONLN dı∂ T¬ s + Note: ° d ONLN d˙∂ s¬„ ) M If your foreign file system returns the tmfoErr result from UTAllocateFCB as ° d ONLN dH¬ TŒ› (À TTthe result to _Open, the Macintosh file system will attempt to enlarge the FCB array ° d ONLN dùŒ T⁄÷ * Sand if successful, will retry the _Open call. Because enlarging the FCB array will ° d ONLN dÒ⁄ TÊ« * Nchange the array’s location in memory, you should never save the location of a ° d ONLN d@Ê TÚ⁄ * NFCBRec between calls to your foreign file system. A FCBRecPtr can only be used ° d ONLN dèÚ T˛2 * 0within the context of one file system operation. ° d ONLN d¿ H ˆ ( HXWhen you no longer need an allocated FCBRec (either because the file could not be opened ° d ONLN d H(\ * :or when the file is closed), release it with UTReleaseFCB. ° d ONLN dT< TH ê + Result codes ° d ONLN daH gT Ç + noErr ° d ONLN dgH ˆT ¸ )è0 ° d ONLN diHTD )%No error ° d ONLN drT g` å (] gtmfoErr ° d ONLN dzT Ï` ¸ )Ö-42 ° d ONLN d~T`Ó )/*There are no free FCBRecs in the FCB array
° d ONLN d∂û H™Ë *RUse the UTReleaseFCB function to release an allocated FCBRec in the FCB array when ° d ONLN d ™ H∂ à * closing a file.
° d ONLN d√ HœP *,pascal OSErr UTReleaseFCB(short fileRefNum);
*%3- )
26 )&The Macintosh Volume Cache ˇ
‘ d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ° d ONLN d U ` a ò ( ^ `
fileRefNum ° d ONLN d U à a˜ )l?Contains the file reference number that specifies the FCBRec to ° d ONLN d K a à m * release. ° d ONLN d T ` ã ( à `XWhen you no longer need an allocated FCBRec (either because the file could not be opened ° d ONLN d ≠ ã ` ó * Wor when the file is closed), release it with UTReleaseFCB. UTReleaseFCB will release an ° d ONLN d ó ` £† * AFCBRec in the FCB array and mark it free (the FCBRec is cleared). ° d ONLN dG ∑ l √ ® + Result codes ° d ONLN dT √ œ ö + noErr ° d ONLN dZ √ œ )è0 ° d ONLN d\ √3 œ\ )%No error ° d ONLN de œ € ¨ ( ÿ fnOpnErr ° d ONLN dn œ € )Ö-38 ° d ONLN dr œ3 €é )/The file is not open ° d ONLN dá € Á Æ ( ‰ rfNumErr ° d ONLN dê € Á )Ö-51 ° d ONLN dî €3 Á„ )/&The file reference number is not valid , Helvetica
° d ONLN dª ` ≈ ( ` UTLocateFCB ^§
° d ONLN d«% `1£ *?Use the UTLocateFCB function to find a FCBRec in the FCB array. ,
Courier
° d ONLN d> `J
*Gpascal OSErr UTLocateFCB(VCBPtr volCtrlBlockPtr, unsigned long fileNum, ° d ONLN dSJ ®VÜ +H %StringPtr namePtr, short *fileRefNum, ° d ONLN d}V ®bV * FCBRecPtr *fileCtrlBlockPtr);
° d ONLN dõm `y ´ (v `volCtrlBlockPtr ° d ONLN d´m Ãy˘ )l@Contains a VCBPtr that specifies the volume the open file is on. ° d ONLN dÏÅ `ç á (ä `fileNum ° d ONLN dÙÅ Ãç )lFContains a file number that specifies the FCBRec to search for. If you ° d ONLN d;ç Ãôˇ * Awant to find the FCBRec by file name, set this parameter to zero. ° d ONLN d}° `≠ á (™ `namePtr ° d ONLN dÖ° Ã≠ )lJContains a pointer to a string that specifies the file name to search for. ° d ONLN d–≠ Ãπ∞ * 1This parameter is ignored if fileNum is not zero. ° d ONLN d¡ `Õ ò ( `
fileRefNum ° d ONLN d
¡ ÃÕ )lDContains a pointer to a short. UTLocateFCB places the file reference ° d ONLN dRÕ ÃŸÓ * =number of the FCBRec found into the field referred to by this ° d ONLN dêŸ Ã ˛ *
parameter. ° d ONLN dõÌ `˘ ´ (ˆ `fileCtrlBlockPtr ° d ONLN d¨Ì Ã˘ )lBContains a pointer to a FCBRecPtr. UTLocateFCB places a pointer to ° d ONLN dÔ˘ ÃÔ * >the FCBRec found into the field referred to by this parameter. ° d ONLN d. `#ˆ ( `QUTLocateFCB will find a FCBRec in the FCB array that’s on the volume specified by ° d ONLN dÄ# `/ * \volCtrlBlockPtr. If fileNum is not zero, UTLocateFCB will search the FCB array for the first ° d ONLN d›/ `; * WFCBRec that has a matching file number. If fileNum is zero, UTLocateFCB will search the ° d ONLN d5; `G * WFCB array for the first FCBRec that has a matching file name. UTLocateFCB always starts ° d ONLN dçG `S„ * Ssearching from the beginning of the FCB array and returns the first match it finds. ° d ONLN d·S `_ * VUTLocateFCB returns the file reference number of the matching FCBRec in fileRefNum and ° d ONLN d8_ `k^ * 5a pointer to the matching FCBRec in fileCtrlBlockPtr. ° d ONLN dn lã ® + Result codes ° d ONLN d{ã ó ö + noErr ° d ONLN dÅãó )è0 ° d ONLN dÉã3ó\ )%No error ° d ONLN dåó £ ú († fnfErr ° d ONLN dìó£ )Ö-38 ° d ONLN dóó3£ )/ A matching FCB was not found ++QThe Macintosh Volume Cache )ß3- )
27 ˇ
L d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager , Helvetica
° d ONLN d U H d Œ *.UTLocateNextFCB d F då
° d ONLN d q H }Ù *TUse the UTLocateNextFCB function to continue seaching for a FCBRec in the FCB array. ,
Courier
° d ONLN d e ä H ñÄ *4pascal OSErr UTLocateNextFCB(VCBPtr volCtrlBlockPtr, ° d ONLN d ¢ ñ ˝ ¢Û +µ )unsigned long fileNum, StringPtr namePtr, ° d ONLN d ‘ ¢ ˝ Æi * short *fileRefNum, ° d ONLN d Ô Æ ˝ ∫´ * FCBRecPtr *fileCtrlBlockPtr);
° d ONLN d
≈ H — ì ( Œ HvolCtrlBlockPtr ° d ONLN d ≈ ¥ —· )l@Contains a VCBPtr that specifies the volume the open file is on. ° d ONLN d^ Ÿ H  o ( ‚ HfileNum ° d ONLN df Ÿ ¥ ² )lFContains a file number that specifies the FCBRec to search for. If you ° d ONLN d≠  ¥ ÒÁ * Awant to find the FCBRec by file name, set this parameter to zero. ° d ONLN dÔ ˘ H o ( HnamePtr ° d ONLN d˜ ˘ ¥˝ )lJContains a pointer to a string that specifies the file name to search for. ° d ONLN dB ¥ò * 1This parameter is ignored if fileNum is not zero. ° d ONLN dt H% Ä (" H
fileRefNum ° d ONLN d ¥%Ì )lFContains a pointer to a short. On input, the field referred to by this ° d ONLN dΔ% ¥1 * Gparameter contains the file reference number of the last match found by ° d ONLN d1 ¥= * :UTLocateFCB or UTLocateNextFCB. On output, UTLocateNextFCB ° d ONLN dI= ¥I * Cplaces the file reference number of the FCBRec found into the field ° d ONLN dçI ¥U= * referred to by this parameter. ° d ONLN d¨] Hi ì (f HfileCtrlBlockPtr ° d ONLN dΩ] ¥i˝ )lBContains a pointer to a FCBRecPtr. UTLocateFCB places a pointer to ° d ONLN d i ¥u◊ * >the FCBRec found into the field referred to by this parameter. ° d ONLN d?á Hìı (ê HUUTLocateNextFCB will find a FCBRec in the FCB array that’s on the volume specified by ° d ONLN dïì Hü˘ * XvolCtrlBlockPtr. If fileNum is not zero, UTLocateNextFCB will search the FCB array for a ° d ONLN dÓü H´¸ * WFCBRec that has a matching file number. If fileNum is zero, UTLocateNextFCB will search ° d ONLN dF´ H∑ˇ * Wthe FCB array for a FCBRec that has a matching file name. UTLocateNextFCB always starts ° d ONLN dû∑ H√Í * Vsearching from the FCBRec specified by fileRefNum and returns the next match it finds. ° d ONLN dı√ Hœ * VUTLocateNextFCB returns the file reference number of the matching FCBRec in fileRefNum ° d ONLN dLœ H€Z * 9and a pointer to the matching FCBRec in fileCtrlBlockPtr. ° d ONLN dÜÔ T˚ ê + Result codes ° d ONLN dì˚ g Ç + noErr ° d ONLN dô˚ ˆ ¸ )è0 ° d ONLN dõ˚D )%No error ° d ONLN d§ g Ñ ( gfnfErr ° d ONLN d´ Ï ¸ )Ö-38 ° d ONLN dØ≤ )/ A matching FCB was not found
° d ONLN dÃ5 HD § (@ H
UTIndexFCB D FDå
° d ONLN d◊Q H]∑ *GUse the UTIndexFCB function to index through the open FCBs on a volume.
° d ONLN d j Hv‘ *Bpascal OSErr UTIndexFCB(VCBPtr volCtrlBlockPtr, short *fileRefNum, ° d ONLN dhv flÇç +ó FCBRecPtr *fileCtrlBlockPtr);
° d ONLN dÜç Hô ì (ñ HvolCtrlBlockPtr ° d ONLN dñç ¥ô· )l@Contains a VCBPtr that specifies the volume the open file is on. (Ò H3- )
28 )&The Macintosh Volume Cache ˇ
d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ° d ONLN d W ` c ò ( ` `
fileRefNum ° d ONLN d W à c )lFContains a pointer to a short. On input, the field referred to by this ° d ONLN d R c à o * Gparameter contains the file reference number of the last match found by ° d ONLN d ö o à {˝ * =UTIndexFCB or zero to search for the first FCBRec. On output, ° d ONLN d ÿ { à á * ?UTIndexFCB places the file reference number of the FCBRec found ° d ONLN d á à ìì * -into the field referred to by this parameter. ° d ONLN dF õ ` ß ´ ( § `fileCtrlBlockPtr ° d ONLN dW õ Ã ß )lAContains a pointer to a FCBRecPtr. UTIndexFCB places a pointer to ° d ONLN dô ß Ã ≥Ô * >the FCBRec found into the field referred to by this parameter. ° d ONLN dÿ ≈ ` —Ú ( Œ `PUTIndexFCB will find a FCBRec in the FCB array that’s on the volume specified by ° d ONLN d) — ` ›˜ * PvolCtrlBlockPtr. UTIndexFCB always starts searching from the FCBRec specified by ° d ONLN dz › ` È * SfileRefNum and returns the next FCBRec it finds on the specified volume. UTIndexFCB ° d ONLN dŒ È ` ı * [returns the file reference number of the matching FCBRec in fileRefNum and a pointer to the ° d ONLN d* ı ` * $matching FCBRec in fileCtrlBlockPtr. ° d ONLN dO l! ® + Result codes ° d ONLN d\! - ö + noErr ° d ONLN db!- )è0 ° d ONLN dd!3-\ )%No error ° d ONLN dm- 9 ú (6 fnfErr ° d ONLN dt-9 )Ö-38 ° d ONLN dx-39 )/ A matching FCB was not found ° d ONLN dï9 E Æ (B rfNumErr ° d ONLN dû9E )Ö-51 ° d ONLN d¢93E„ )/&The file reference number is not valid , Helvetica
° d ONLN d…g `v Œ (r ` UTResolveFCB v ^v§
° d ONLN d÷É `è⁄ *KUse the UTResolveFCB function to map a file reference number to its FCBRec. ,
Courier
° d ONLN d"ú `®b *+pascal OSErr UTResolveFCB(short fileRefNum, ° d ONLN dV®¥√ +µ FCBRecPtr *fileCtrlBlockPtr);
° d ONLN dtø `À ò (» `
fileRefNum ° d ONLN dø ÃÀÊ )l;Contains a file reference number that specifies the FCBRec. ° d ONLN dª” `fl ´ (‹ `fileCtrlBlockPtr ° d ONLN dÔ Ãfl )l@Contains a pointer to a FCBRecPtr. UTResolveFCB places a pointer ° d ONLN d
fl ÃÎ˚ * Ato the FCBRec found into the field referred to by this parameter. ° d ONLN dO˝ ` ‹ ( `LGiven a file reference number, UTResolveFCB returns a pointer to a FCBRec in ° d ONLN dú ` Ø * fileCtrlBlockPtr. ° d ONLN dÆ! `- *^If the file reference number is valid, UTResolveFCB will return noErr; even if the file is not ° d ONLN d
- `9
* Wopen. You can use UTCheckFileRefNum to see if a file reference number refers to an open ° d ONLN de9 `E s * file. ° d ONLN dkY le ® + Result codes ° d ONLN dxe q ö + noErr ° d ONLN d~eq )è0 ° d ONLN dÄe3q\ )%No error ° d ONLN dâq } Æ (z rfNumErr ° d ONLN díq} )Ö-51 ° d ONLN dñq3}„ )/&The file reference number is not valid
° d ONLN dΩü `Æ Œ (™ `
UTAllocateVCB Æ ^Ƨ
° d ONLN dÀª `« *SUse the UTAllocateVCB function to allocate memory in the system heap for a new VCB. +˛-The Macintosh Volume Cache )ß3- )
29 ˇ
⁄ d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager ,
Courier
° d ONLN d U H aò *,8pascal OSErr UTAllocateVCB(unsigned short *sysVCBLength, ° d ONLN d A a ˝ mç +µ VCBPtr *volCtrlBlockPtr, ° d ONLN d b m ˝ yç * unsigned short addSize);
° d ONLN d { Ñ H ê ë ( ç H sysVCBLength ° d ONLN d à Ñ ¥ êÛ )lAContains a pointer to an unsigned short. UTAllocateVCB places the ° d ONLN d ê ¥ úÌ * Dsize of the system VCB into the field referred to by this parameter. ° d ONLN d § H ∞ ì ( ≠ HvolCtrlBlockPtr ° d ONLN d § ¥ ∞˙ )lBContains a pointer to an VCBPtr. UTAllocateVCB places a pointer to ° d ONLN db ∞ ¥ ºæ * 9the new VCB into the field referred to by this parameter. ° d ONLN dú ƒ H – m ( Õ HaddSize ° d ONLN d§ ƒ ¥ –˚ )lHContains the amount of addition storage to allocate for the foreign file ° d ONLN dÌ – ¥ ‹@ * system’s private use, or zero. ° d ONLN d Ó H ˙Î ( ˜ HRUTAllocateVCB will allocate cleared memory from the system heap for a new VCB. The ° d ONLN d_ ˙ HÊ * Samount of memory allocated by UTAllocateVCB is determined by adding the size of the ° d ONLN d≥ Hÿ * Ssystem VCB structure to the amount of additional memory needed for the foreign file ° d ONLN d H * ]system’s private use. A pointer to the new VCB is returned in volCtrlBlockPtr and the size of ° d ONLN de H*Í * Wthe system VCB structure is returned in sysVCBLength. Thus, the additional foreign file ° d ONLN dΩ* H6ó * Fsystem private data (if any) starts at volCtrlBlockPtr + sysVCBLength. ° d ONLN dJ TV ê + Result codes ° d ONLN dV gb Ç + noErr ° d ONLN dV ˆb ¸ )è0 ° d ONLN dVbD )%No error ° d ONLN d"b gn † (k g
memFullErr ° d ONLN d-b Ên ¸ )-108 ° d ONLN d2bnÌ )5)The VCB could not be allocated; no memory ° d ONLN d_nzD * available , Helvetica
° d ONLN diú H´ ∑ (ß H UTAddNewVCB ´ F´å
° d ONLN du∏ Hƒ *RUse the UTAddNewVCB function to add a new VCB to the VCB queue and assign a volume ° d ONLN d»ƒ H– · * reference number to the volume.
° d ONLN dË› HÈò *8pascal OSErr UTAddNewVCB(short driveNum, short *vRefNum, ° d ONLN d(È flıo +ó VCBPtr volCtrlBlockPtr);
° d ONLN dA H x ( HdriveNum ° d ONLN dJ ¥ ø )l8Contains the drive number of the drive the volume is on. ° d ONLN dÉ H w ( HvRefNum ° d ONLN dã ¥ Í )l<Contains a pointer to a short. UTAddNewVCB places the volume ° d ONLN d» ¥,ˆ * Ereference number assigned to the volume into the field referred to by ° d ONLN d, ¥8 ˙ * this parameter. ° d ONLN d @ HL ì (I HvolCtrlBlockPtr ° d ONLN d.@ ¥LΩ )l6Contains a pointer to the VCB to add to the VCB queue. ° d ONLN de^ HjÒ (g HQUTAddNewVCB assigns an unused volume reference number to a VCB and adds it to the ° d ONLN d∑j Hvä * >VCB queue. The volume reference number is returned in vRefNum. ° d ONLN dˆÇ Héú *CThe following fields in the VCB are also initialized by UTAddNewVCB ° d ONLN d:ö T¶ X + • ° d ONLN d<ö a¶ ˜ )
qType is assigned fsQType (5). ° d ONLN d[≤ Tæ X (ª T• ° d ONLN d]≤ aæ∞ )
DvcbDrvNum is assigned the drive number of the drive the volume is on ° d ONLN d¢ T÷ X (” T• ° d ONLN d§ a÷È )
PvcbDRefNum is assigned the driver reference number of the drive the volume is on (Ò H3- )
30 )&The Macintosh Volume Cache ˇ Ü d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ° d ONLN d U l a p ( ^ l• ° d ONLN d U y a~ )
2vcbVRefNum is assigned the volume reference number ° d ONLN d 5 m l y p ( v l• ° d ONLN d 7 m y y¶ )
=vcbBufAdr may be assigned a value for the system’s cache use. ° d ONLN d u Ö ` ë ( é `YIf the VCB is the first VCB added to the VCB queue (this will probably never happen for a ° d ONLN d œ ë ` ùÚ * Oforeign file system), UTAddNewVCB will also make the volume the default volume. ° d ONLN d ± l Ω ® + Result codes ° d ONLN d, Ω … ö + noErr ° d ONLN d2 Ω … )è0 ° d ONLN d4 Ω3 …\ )%No error ° d ONLN d= … ’ ´ ( “ paramErr ° d ONLN dF … ’ )Ö-50 ° d ONLN dJ …3 ’∑ )/volCtrlBlockPtr was NULL ° d ONLN dc ’ · ´ ( fi nsDrvErr ° d ONLN dl ’ · )Ö-56 ° d ONLN dp ’3 · )/,The drive specified by driveNum could not be ° d ONLN d† ·3 ̶ * found in the drive queue , Helvetica
° d ONLN dπ ` Œ ( ` UTDisposeVCB ^ §
° d ONLN dΔ+ `7 *RUse the UTDisposeVCB function to dispose of a VCB allocated with the UTAllocateVCB ° d ONLN d7 `C ã * function. ,
Courier
° d ONLN d#P `\å *2pascal OSErr UTDisposeVCB(VCBPtr volCtrlBlockPtr);
+Close all working directories on the volume ° d ONLN d‚µ l¡ p (æ l• ° d ONLN d‰µ y¡1 )
!Remove the VCB from the VCB queue ° d ONLN dÕ lŸ p (÷ l• ° d ONLN dÕ yŸ )
XIf the volume’s drive is ejectable, clear the dQFSID field in the DrvQEl of the volume’s ° d ONLN daŸ y½ * Tdrive (a disk owned by another file system could be the next disk inserted into the ° d ONLN d∂ yÒ ¿ * ejectable drive) ° d ONLN d«˝ l p ( l• ° d ONLN d…˝ y ¡ )
FIf the volume is the default volume, clear the system’s default volume ° d ONLN d l! p ( l• ° d ONLN d y!; )
%Dispose of the memory used by the VCB ° d ONLN d8- `9˘ (6 `PYou should always use UTDisposeVCB to dispose of your VCB instead of freeing the ° d ONLN dâ9 `E µ * memory yourself. +˛ØThe Macintosh Volume Cache )ß3- )
31 ˇ é d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager ° d ONLN d i T u ê + @ Result codes ° d ONLN d
u g Å Ç + noErr ° d ONLN d u ˆ Å ¸ )è0 ° d ONLN d u ÅD )%No error ° d ONLN d Å g ç ì ( ä gnsDrvErr ° d ONLN d ' Å Ï ç ¸ )Ö-56 ° d ONLN d + Å ç )/,The volume’s drive could not be found in the ° d ONLN d [ ç ôR * drive queue , Helvetica
° d ONLN d g ª H ˘ ( Δ HUTLocateVCBByRefNum F å
° d ONLN d { ◊ H „› *MUse the UTLocateVCBByRefNum function to locate a VCB using a volume reference ° d ONLN d … „ H ÔG * 2number, drive number, or working.directory number. ,
Courier
° d ONLN d ¸ ¸ Hº *>pascal OSErr UTLocateVCBByRefNum(short refNum, short *vRefNum, ° d ONLN dD ∂ +ÿ VCBPtr *volCtrlBlockPtr);
° d ONLN d^ H+ m (( HrefNum ° d ONLN de ¥+„ )l<Contains a volume reference number, drive number, or working ° d ONLN d¢+ ¥7 * directory number. ° d ONLN d¥? HK w (H HvRefNum ° d ONLN dº? ¥KÔ )l=Contains a pointer to a short. UTLocateVCBByRefNum places the ° d ONLN d˙K ¥W˛ * Greference number of the volume found into the field referred to by this ° d ONLN dBW ¥c Ê *
parameter. ° d ONLN dMk Hw ì (t HvolCtrlBlockPtr ° d ONLN d]k ¥wÙ )l<Contains a pointer to a VCBPtr. UTLocateVCBByRefNum places a ° d ONLN döw ¥Éˆ * Fpointer to the VCB found into the field referred to by this parameter. ° d ONLN d·ï H°˙ (û HRUTLocateVCBByRefNum finds the VCB associated with a volume reference number, drive ° d ONLN d4° H≠Û * Wnumber, or working.directory number and returns a pointer to the VCB in volCtrlBlockPtr ° d ONLN då≠ Hπ' * +and the volume reference number in vRefNum. ° d ONLN d∏Õ TŸ ê + Result codes ° d ONLN d≈Ÿ gÂ Ç + noErr ° d ONLN dÀŸ ˆÂ ¸ )è0 ° d ONLN dÕŸÂD )%No error ° d ONLN d÷ gÒ ñ (Ó grfNumErr ° d ONLN dfl ÏÒ ¸ )Ö-51 ° d ONLN d„ÂÒ )/)The working directory reference number is ° d ONLN dÒ˝; * invalid ° d ONLN d˝ g á ( gnsvErr ° d ONLN d ˝ Ï ¸ )Ö-56 ° d ONLN d#˝ )/+A matching volume could not be found in the ° d ONLN dR R * VCB queue
° d ONLN d\7 HF È (B HUTLocateVCBByName F FFå
° d ONLN dnS H_Í *RUse the UTLocateVCBByName function to locate the first VCB that matches the volume ° d ONLN d¡_ Hk í * name specified.
° d ONLN d—x HÑÊ *Epascal OSErr UTLocateVCBByName(StringPtr namePtr, short *moreMatches, ° d ONLN d Ñ ˝êÌ +µ (short *vRefNum, VCBPtr *volCtrlBlockPtr)
° d ONLN dHõ Hß o (§ HnamePtr ° d ONLN dPõ ¥ß˝ )lDContains a pointer to a volume name (which must end with a colon ‘:’ ° d ONLN dïß ¥≥J * !character) or to a full pathname. (Ò H3- )
32 )&The Macintosh Volume Cache ˇ d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ° d ONLN d W ` c ü ( ` ` moreMatches ° d ONLN d W à cÒ )l@Contains a pointer to a short. If there is another volume with a ° d ONLN d M c à o˙ * 9matching name, UTLocateVCBByName places the length of the ° d ONLN d á o à { * Ivolume name (not including the trailing colon) into the field referred to ° d ONLN d — { à á * Eby this parameter. If this is the last volume with a matching name or ° d ONLN d á à ì * <no matches are found, UTLocateVCBByName places zero into the ° d ONLN dT ì à üm * $field referred to by this parameter. ° d ONLN dy ß ` ≥ è ( ∞ `vRefNum ° d ONLN dÅ ß Ã ≥˙ )l;Contains a pointer to a short. UTLocateVCBByName places the ° d ONLN dΩ ≥ à ø * Greference number of the volume found into the field referred to by this ° d ONLN d ø à À ˛ *
parameter. ° d ONLN d ” ` fl ´ ( ‹ `volCtrlBlockPtr ° d ONLN d ” à flˇ )l:Contains a pointer to a VCBPtr. UTLocateVCBByName places a ° d ONLN d[ fl à Π* Fpointer to the VCB found into the field referred to by this parameter. ° d ONLN d¢ ˝ ` ( `RUTLocateVCBByName finds the first VCB with the specified volume name and returns a ° d ONLN dı `ı * Qpointer to the VCB in volCtrlBlockPtr and the volume reference number in vRefNum. ° d ONLN dG! `- *TUTLocateVCBByName also checks to see if there are more volumes in the VCB queue with ° d ONLN dú- `9 * [the specified name. If there are, moreMatches returns the length of the volume name. If the ° d ONLN d¯9 `E * Vvolume found is the only volume with the specified name (or if no matching volumes are ° d ONLN dOE `Q * Wfound), moreMatches returns zero. To find the next volume with a matching name, use the ° d ONLN dßQ `] Ê * UTLocateNextVCB routine. ° d ONLN d¿q l} ® + Result codes ° d ONLN dÕ} â ö + noErr ° d ONLN d”}â )è0 ° d ONLN d’}3â\ )%No error ° d ONLN dfiâ ï ± (í bdNamErr ° d ONLN dÁâï )Ö-37 ° d ONLN dÎâ3ï )/+namePtr was NULL, or namePtr does not point ° d ONLN dï3°÷ * !to a volume name or full pathname ° d ONLN d=° ≠ ü (™ nsvErr ° d ONLN dD°≠ )Ö-56 ° d ONLN dH°3≠ )/+A matching volume could not be found in the ° d ONLN dw≠3πj * VCB queue , Helvetica
° d ONLN dÅ€ `Í Ê (Ê `UTLocateNextVCB Í ^ͧ
° d ONLN dë˜ ` *RUse the UTLocateNextVCB function to continue seaching for a VCB by name in the VCB ° d ONLN d‰ ` Ä * queue. ,
Courier
° d ONLN dÎ `(Ú *Cpascal OSErr UTLocateNextVCB(StringPtr namePtr, short *moreMatches, ° d ONLN d7(4 +µ )short *vRefNum, VCBPtr *volCtrlBlockPtr);
° d ONLN da? `K á (H `namePtr ° d ONLN di? ÃK )lDContains a pointer to a volume name (which must end with a colon ‘:’ ° d ONLN dÆK ÃWb * !character) or to a full pathname. ° d ONLN d–_ `k ü (h ` moreMatches ° d ONLN d‹_ Ãk )lFContains a pointer to a short. On input, the field referred to by this ° d ONLN d#k Ãw * Aparameter contains the length of the volume name as returned by a ° d ONLN dew ÃÉ * 9previous call to UTLocateVCBByName or UTLocateNextVCB, or ° d ONLN düÉ Ãè * Bzero to force UTLocateNextVCB to re-parse the pathname. On output, ° d ONLN d‚è ÃõÒ * 9UTLocateNextVCB places the length of the volume name (not ° d ONLN d õ Ãß * Kincluding the trailing colon) into the field referred to by this parameter. ° d ONLN dhß Ã≥˝ * AIf this is the last volume with a matching name or no matches are ° d ONLN d™≥ Ãø * Dfound UTLocateNextVCB places zero into the field referred to by this ° d ONLN dÔø ÃÀ ˛ *
parameter. +í)The Macintosh Volume Cache )ß3- )
33 ˇÃ d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager ° d ONLN d U H a w *,vRefNum ° d ONLN d U ¥ a˝ )lCContains a pointer to a short. UTLocateNextVCB places the reference ° d ONLN d L a ¥ m– * =number of the volume found into the field referred to by this ° d ONLN d ä m ¥ y Ê *
parameter. ° d ONLN d ï Å H ç ì ( ä HvolCtrlBlockPtr ° d ONLN d • Å ¥ ç¯ )l@Contains a pointer to a VCBPtr. UTLocateNextVCB places a pointer ° d ONLN d Ê ç ¥ ô“ * >to the VCB found into the field referred to by this parameter. ° d ONLN d% ´ H ∑ ( ¥ HRUTLocateNextVCB finds the next VCB with the specified volume name. UTLocateNextVCB ° d ONLN dx ∑ H √ * Zalways starts searching from the VCB specified by volCtrlBlockPtr and returns the next VCB ° d ONLN d” √ H œπ * Jit finds in the VCB queue. UTLocateNextVCB returns a pointer to the VCB in ° d ONLN d œ H €u * ;volCtrlBlockPtr and the volume reference number in vRefNum. ° d ONLN dZ Á H Û *ZAfter finding a match, UTLocateNextVCB also checks to see if there are more volumes in the ° d ONLN dµ Û H ˇ‰ * VVCB queue with the specified name. If there are, moreMatches returns the length of the ° d ONLN d ˇ H ‚ * Uvolume name. If the volume found is the only volume with the specified name (or if no ° d ONLN db HW * 6matching volumes are found), moreMatches returns zero. ° d ONLN dô+ T7 ê + Result codes ° d ONLN d¶7 gC Ç + noErr ° d ONLN d¨7 ˆC ¸ )è0 ° d ONLN dÆ7CD )%No error ° d ONLN d∑C gO ô (L gbdNamErr ° d ONLN d¿C ÏO ¸ )Ö-37 ° d ONLN dƒCO¸ )/+namePtr was NULL, or namePtr does not point ° d ONLN dÛO[æ * !to a volume name or full pathname ° d ONLN d[ gg á (d gnsvErr ° d ONLN d [ Ïg ¸ )Ö-56 ° d ONLN d![g )/+A matching volume could not be found in the ° d ONLN dPgsR * VCB queue , Helvetica
° d ONLN dZï H§ ≈ († HUTAllocateWDCB § F§
° d ONLN di± HΩÊ *RUse the UTAllocateWDCB function to allocate a working directory in the WDCB array. ,
Courier
° d ONLN dº H÷h *0pascal OSErr UTAllocateWDCB(WDPBPtr paramBlock);
° d ONLN dÌ· HÌ Å *
paramBlock ° d ONLN d¯· ¥Ì» )l:Contains a pointer to a working directory parameter block. ° d ONLN d3 T ± ( TParameter Block , Symbol ° d ONLN dC T$ a *´ ° d ONLN dE g# ° ) ioVRefNum ° d ONLN dO ÿ# )qshort ° d ONLN dU;#˜ )c'On input, contains the volume reference ° d ONLN dÅ$;0‘ *
number. On output, contains the ° d ONLN d•0;<È * #working directory reference number. ° d ONLN d…< TM ` (I T¨ ° d ONLN dÀ@ gL ß ) ioWDCreated ° d ONLN d◊@ ÿL )qshort ° d ONLN d›@;LË )c&If a working directory is not created, ° d ONLN dM;YÛ *
(zero is returned. If a working directory ° d ONLN d5Y;e— * !is created, non-zero is returned. ° d ONLN dWe Tv ` (r TÆ ° d ONLN dYi gu • )
ioWDProcID ° d ONLN ddi ÿu Ì )qlong ° d ONLN dii;u )c#Contains the working directory user ° d ONLN dëv;Çi *
directory ID. ° d ONLN d·Ø Hª‘ (∏ HJUTAllocateWDCB uses the ioVRefNum, ioWDProcID, and ioPDDirID fields in the ° d ONLN d,ª H«˝ * TWDPBRec to allocate a working directory in the WDCB array. UTAllocateWDCB places the ° d ONLN dÅ« H”Δ * Kworking directory reference number into the ioVRefNum field of the WDPBRec. *!3- )
34 )&The Macintosh Volume Cache ˇ ^ d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ° d ONLN d U ` aÈ ( ^ `SIf the specified directory has already been made a working directory using the same ° d ONLN d T a ` m˙ * VioWDProcID value, a new working directory will not be allocated; instead, the existing ° d ONLN d ´ m ` y * Xworking directory reference number will be returned and ioWDCreated will be set to zero. ° d ONLN d Ö l ë ì + Note: ° d ONLN d Ö ì ëfi )'FThe ioWDCreated field is named filler1 in current versions of Files.C. ° d ONLN dR £ ` Ø∑ ( ¨ `IIf a WDCB array cannot be allocated, this function will return a tmfoErr. ° d ONLN dú ª l « ã + Note: ° d ONLN d° ª ã «Ò ) I If all WDCBRecs in the WDCB array are in use, an attempt will be made to ° d ONLN dÎ « l ”˝ ( – lPenlarge the WDCB array. Because enlarging the WDCB array will change the array’s ° d ONLN d< ” l fl * Qlocation in memory, you should never save the location of a WDCBRec between calls ° d ONLN dé fl l ÎÙ * Pto your foreign file system. A WDCBRecPtr can only be used within the context of ° d ONLN dfl Î l ˜ Ê * one file system operation. ° d ONLN d˙ ` ( `VWhen you no longer need an allocated working directory, release it with UTReleaseWDCB. ° d ONLN dQ) l5 ® + Result codes ° d ONLN d^5 A ö + noErr ° d ONLN dd5A )è0 ° d ONLN df53A\ )%No error ° d ONLN doA M § (J tmfoErr ° d ONLN dwAM )Ö-42 ° d ONLN d{A3M )/&There are no free WDCBRecs in the WDCB ° d ONLN d•M3YK * array , Helvetica
° d ONLN d´{ `ä fi (Ü `
UTReleaseWDCB ä ^ä§
° d ONLN dπó `£ *TUse the UTReleaseWDCB function to release an allocated working directory in the WDCB ° d ONLN d£ `Ø * 'array when closing a working directory. ,
Courier
° d ONLN d6º `»b *+pascal OSErr UTReleaseWDCB(short wdRefNum);
° d ONLN db” `fl ò *wdRefNum ° d ONLN dk” Ãfl )lBContains the working directory reference number that specifies the ° d ONLN dÆfl ÃÎT * working directory to release. ° d ONLN dÃ˝ ` ( `VWhen you no longer need an allocated working directory, release it with UTReleaseWDCB. ° d ONLN d# `‰ * IUTReleaseWDCB will release an WDCBRec in the WDCB array and mark it free. ° d ONLN dm) l5 ® + Result codes ° d ONLN dz5 A ö + noErr ° d ONLN dÄ5A )è0 ° d ONLN dÇ53A\ )%No error ° d ONLN dãA M Æ (J rfNumErr ° d ONLN dîAM )Ö-51 ° d ONLN dòA3M )/-The working directory reference number is not ° d ONLN d…M3Y˙ * *valid or does not refer to an open working ° d ONLN d˜Y3e] * directory
° d ONLN dá `ñ › (í `
UTResolveWDCB ñ ^ñ§
° d ONLN d£ `ØŒ *CUse the UTResolveWDCB function to find a WDCBRec in the WDCB array.
° d ONLN dSº `» *Fpascal OSErr UTResolveWDCB(long procID, short wdIndex, short wdRefNum, ° d ONLN d¢»‘Ω +µ WDCBRecPtr *wdCtrlBlockPtr);
+I The Macintosh Volume Cache )ß3- )
35 ˇ
Δ d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager ° d ONLN d U H a i *,procID ° d ONLN d U ¥ a¶ )l4Contains a working directory user identifier or zero ° d ONLN d < i H u r ( r HwdIndex ° d ONLN d D i ¥ u
parameter. ° d ONLN dú fl H Î◊ ( Ë HKUTResolveWDCB locates a WDCBRec in the WDCB array according to these rules: ° d ONLN dË ˜ T X + • ° d ONLN dÍ ˜ a˛ )
RIf wdIndex is zero or negative, UTResolveWDCB uses the working directory reference ° d ONLN d= a˜ * Onumber in wdRefNum to find the WDCBRec. The procID parameter is ignored in this ° d ONLN dç a y * case. ° d ONLN dì' T3 X (0 T• ° d ONLN dï' a3Á )
JIf wdIndex is positive and procID is zero, UTResolveWDCB finds the WDCBRec ° d ONLN d·3 a?Ó * Mwhose working directory index is wdIndex on the volume specified by wdRefNum. ° d ONLN d/K TW X (T T• ° d ONLN d1K aW˝ )
NIf wdIndex is positive and procID is non-zero, UTResolveWDCB finds the WDCBRec ° d ONLN dÅW acÚ * Swhose working directory index is wdIndex with the working directory user identifier ° d ONLN d’c ao * 8specified by procID on the volume specified by wdRefNum. ° d ONLN dÉ Tè ê (å T Result codes ° d ONLN dè gõ Ç + noErr ° d ONLN d!è ˆõ ¸ )è0 ° d ONLN d#èõD )%No error ° d ONLN d,õ gß á (§ gnsvErr ° d ONLN d3õ Ïß ¸ )Ö-35 ° d ONLN d7õßÙ )/*No matching working directory was found by ° d ONLN deß≥r * the indexed search ° d ONLN dx≥ gø ñ (º grfNumErr ° d ONLN dÅ≥ Ïø ¸ )Ö-51 ° d ONLN dÖ≥ø˜ )/-The working directory reference number is not ° d ONLN d∂øÀ‚ * *valid or does not refer to an open working ° d ONLN d‰À◊E * directory , Helvetica
° d ONLN dÓ˘ H £ ( H UTFindDrive Få
° d ONLN d˙ H!ø *NUse the UTFindDrive function to find a drive queue element in the drive queue. ,
° d ONLN dêE HQ x *driveNum ° d ONLN dôE ¥Q° )l3Contains the drive number that specifies the drive. ° d ONLN dÕY He ú (b HdriveQElementPtr ° d ONLN dfiY ¥eÚ )lBContains a pointer to a DrvQElPtr. UTFindDrive places a pointer to ° d ONLN d!e ¥q◊ * @the drive queue element found into the field referred to by this ° d ONLN dbq ¥} Ê *
parameter. ° d ONLN dmè HõÍ (ò HWUTFindDrive locates a drive queue element in the drive queue. If a matching drive queue ° d ONLN d≈õ Hß˚ * [element is found and its dQFSID field is zero, UTFindDrive will return noErr. If a matching ° d ONLN d!ß H≥˚ * [drive queue element is found and its dQFSID field is not zero (when the drive is owned by a ° d ONLN d}≥ HøQ * 7foreign file system), UTFindDrive will return extFSErr. *53- )
36 )&The Macintosh Volume Cache ˇ z d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ° d ONLN d U l a ® ( ^ l Result codes ° d ONLN d
a m ö + noErr ° d ONLN d a m )è0 ° d ONLN d a3 mˇ )%(A matching drive queue element was found ° d ONLN d A m3 y™ * with a zero dQFSID field ° d ONLN d Z y Ö ´ ( Ç nsDrvErr ° d ONLN d c y Ö )Ö-56 ° d ONLN d g y3 Ö )/)No matching drive queue element was found ° d ONLN d ë Ö ë ™ ( é extFSErr ° d ONLN d ö Ö ë )Ö-58 ° d ONLN d û Ö3 ëˇ )/(A matching drive queue element was found ° d ONLN d ë3 ù¿ * with a non-zero dQFSID field , Helvetica
° d ONLN d Á ø ` Œ ¬ ( ` UTAdjustEOF Œ ^ Œ§
° d ONLN d Û € ` Á *XUse the UTAdjustEOF function to adjust the logical and physical EOF of all open FCBs for ° d ONLN dL Á ` Û » * the specified file fork. ,
Courier
° d ONLN de ` b *+pascal OSErr UTAdjustEOF(short fileRefNum);
° d ONLN dë `# ò *
fileRefNum ° d ONLN dú Ã# )lEContains a file reference number that specifies the reference FCBRec. ° d ONLN d‚5 `A (> `WUTAdjustEOF finds the open FCB specified by fileRefNum and gets that file’s file number ° d ONLN d:A `M * Xand VCBPtr. UTAdjustEOF then copies the logical end of file (fcbEOF) and physical end of ° d ONLN dìM `Y * Yfile (fcbPLen) from the specified FCBRec to all other open FCBRecs that refer to the same ° d ONLN dÌY `e ä *
file fork. ° d ONLN d¯y lÖ ® + Result codes ° d ONLN dÖ ë ö + noErr ° d ONLN d Öë )è0 ° d ONLN d
Ö3ë\ )%No error ° d ONLN dë ù Æ (ö rfNumErr ° d ONLN d ëù )Ö-51 ° d ONLN d#ë3ù„ )/&The file reference number is not valid
° d ONLN dJø `Œ ÿ ( `UTSetDefaultVol Œ ^Œ§
° d ONLN dZ€ `Á *ZUse UTSetDefaultVol to set the default volume and working directory in response to _SetVol ° d ONLN dµÁ `Û † * or _HSetVol.
° d ONLN d¬ ` ‡ *@pascal OSErr UTSetDefaultVol(long nodeHint, unsigned long dirID, ° d ONLN d
i +µ short refNum);
° d ONLN d# `/ å (, `nodeHint ° d ONLN d"# Ã/ )lHContains a long that specifies optional file system specific information ° d ONLN dk/ Ã;( * about the directory. ° d ONLN dÄC `O y (L `dirID ° d ONLN dÜC ÃOT )l Contains a directory ID or 0. ° d ONLN d§W `c Ö (` `refNum ° d ONLN d´W Ãc )lAContains a volume reference number or a working directory number. ° d ONLN dÌu `Å˘ (~ `SThe parameters you pass to UTSetDefaultVol depend on which file system call you are ° d ONLN dAÅ `ç¸ * Vresponding to, _SetVol or _HSetVol, and on the parameters passed the file system call. ° d ONLN dòô `•˘ *RIf you are responding to _SetVol and ioVRefNum is a working directory number, then ° d ONLN dΕ `± * TrefNum must be set to the working directory number (ioVRefNum), dirID must be 0, and ° d ONLN d@± `Ω * \nodeHint is ignored (nodeHint information is obtained from the working directory specified). +˛7The Macintosh Volume Cache )ß3- )
"NULL. If not NULL, UTGetDefaultVol ° d ONLN d ¬;Œ * *will return the volume’s name in the Str31 ° d ONLN dLŒ;⁄§ * specified by this field. ° d ONLN de⁄ TÎ ` (Á T¨ ° d ONLN dgfi gÍ ° ) ioVRefNum ° d ONLN dqfi ÿÍ )qshort ° d ONLN dwfi;ÍÎ )c"UTGetDefaultVol places the working ° d ONLN dûÎ;˜Û *
&directory number of the default volume ° d ONLN d…˜;t * in this field. ° d ONLN dŸ T ` ( T¨ ° d ONLN d€ g • )
ioWDProcID ° d ONLN dÊ ÿ Ì )qlong ° d ONLN dÎ;Î )c"UTGetDefaultVol places the working ° d ONLN d; Â *
(directory user identifier in this field. ° d ONLN d; T1 ` (- T¨ ° d ONLN d=$ g0 ¥ ) ioWDVRefNum ° d ONLN dI$ ÿ0 )qshort ° d ONLN dO$;0Ê )c!UTGetDefaultVol places the volume ° d ONLN du1;=Ù *
&reference number of the default volume ° d ONLN d†=;It * in this field. ° d ONLN dØI TZ ` (V T¨ ° d ONLN d±M gY û ) ioWDDirID ° d ONLN dªM ÿY Ì )qlong ° d ONLN d¿M;YÌ )c$UTGetDefaultVol places the directory ° d ONLN dÈZ;fË *
%ID number of the default directory in ° d ONLN df;rh * this field. ° d ONLN d Ç Héı (ã HWUTGetDefaultVol returns the default volume name, the default volume’s working directory ° d ONLN dwé Hö˝ * [number, the default volume’s user identifier, the default volume’s volume reference number, ° d ONLN d”ö H¶* * 0and the default directory’s directory ID number. *N3- )
38 )&The Macintosh Volume Cache ˇ d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ° d ONLN d U l a ® ( ^ l Result codes ° d ONLN d
a m ö + noErr ° d ONLN d a m )è0 ° d ONLN d a3 m\ )%No error ° d ONLN d m y ü ( v nsvErr ° d ONLN d % m y )Ö-35 ° d ONLN d ) m3 y¬ )/ The default directory is not set , Helvetica
° d ONLN d J õ ` ™ ∞ ( ¶ `
UTEjectVol ™ ^ ™§
° d ONLN d U ∑ ` √^ *5Use UTEjectVol to eject a volume and mark it offline. ,
Courier
° d ONLN d ã – ` ‹Ä *0pascal OSErr UTEjectVol(VCBPtr volCtrlBlockPtr);
° d ONLN d º Á ` Û ´ *volCtrlBlockPtr ° d ONLN d à Á Ã Û )lFContains a pointer to the VCB of the volume to eject and mark offline. ° d ONLN d ` ( `ZUTEjectVol ejects and marks offline the volume specified by volCtrlBlockPtr. If the volume ° d ONLN dn ` ˜ * Uhas already been ejected, UTEjectVol does nothing and returns noErr. If the volume is ° d ONLN dƒ `)î * Dalready offline, but has not been ejected, UTEjectVol will eject it. ° d ONLN d 5 `A *[If the volume’s drive is ejectable, UTEjectVol clears the dQFSID field in the DrvQEl of the ° d ONLN deA `M * \volume’s drive (a disk owned by another file system could be the next disk inserted into the ° d ONLN d¬M `Y ´ * ejectable drive). ° d ONLN d‘e lq ã + Note: ° d ONLN dŸe ãq˝ ) N Before calling UTEjectVol, the foreign file system must flush any cached data ° d ONLN d(q l}Œ (z lJassociated with the volume using UTFlushCache. If the device is ejectable, ° d ONLN ds} lâ’ * JUTFlushCache's fcOption should be set to fcTrashMask. If the device is not ° d ONLN dæâ lïô * >ejectable, UTFlushCache's rbOption should be set to rbDefault. ° d ONLN d˝Ø lª ® *& Result codes ° d ONLN d
ª « ö + noErr ° d ONLN dª« )è0 ° d ONLN dª3«\ )%No error ° d ONLN d« ” ´ (– paramErr ° d ONLN d$«” )Ö-50 ° d ONLN d(«3”
)/-volCtrlBlockPtr does not point to a valid VCB ° d ONLN dV” flÆ (‹ Dany of the result codes returned by the disk driver to an eject call
° d ONLN dõ ` ı ( `UTCheckWDRefNum ^§
° d ONLN d´ `)
*RUse UTCheckWDRefNum to make sure a working directory reference number is valid and ° d ONLN d˛) `5 { * open.
° d ONLN dB `Nn *-pascal OSErr UTCheckWDRefNum(short wdRefNum);
° d ONLN d2Y `e ò *wdRefNum ° d ONLN d;Y Ãe∏ )l0Contains the working directory reference number. ° d ONLN dlw `É (Ä `VUTCheckWDRefNum will return noErr if a working directory reference number is valid and ° d ONLN d√É `è { * open. +˛eThe Macintosh Volume Cache )ß3- )
39 ˇ
V d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager ° d ONLN d i T u ê + @ Result codes ° d ONLN d
u g Å Ç + noErr ° d ONLN d u ˆ Å ¸ )è0 ° d ONLN d u ÅD )%No error ° d ONLN d Å g ç ñ ( ä grfNumErr ° d ONLN d ' Å Ï ç ¸ )Ö-51 ° d ONLN d + Å ç˜ )/-The working directory reference number is not ° d ONLN d \ ç ô‚ * *valid or does not refer to an open working ° d ONLN d ä ô •E * directory , Helvetica
° d ONLN d î « H ÷ fl ( “ HUTCheckFileRefNum ÷ F ÷å
° d ONLN d ¶ „ H ÔÃ *MUse UTCheckFileRefNum to make sure a file reference number is valid and open. ,
Courier
° d ONLN d Ù ¸ Hn *1pascal OSErr UTCheckFileRefNum(short fileRefNum);
° d ONLN d& H Ä *
fileRefNum ° d ONLN d1 ¥ Z )l#Contains the file reference number. ° d ONLN dU1 H=” (: HQUTCheckFileRefNum will return noErr if a file reference number is valid and open. ° d ONLN dßQ T] ê + Result codes ° d ONLN d¥] gi Ç + noErr ° d ONLN d∫] ˆi ¸ )è0 ° d ONLN dº]iD )%No error ° d ONLN d≈i gu ñ (r grfNumErr ° d ONLN dŒi Ïu ¸ )Ö-51 ° d ONLN d“iuÒ )/.The file reference number is not valid or does ° d ONLN duÅâ * not refer to an open file
° d ONLN d £ H≤ € (Æ HUTCheckVolRefNum ≤ F≤å
° d ONLN d/ø HÀ± *EUse UTCheckVolRefNum to make sure a volume reference number is valid.
° d ONLN duÿ H‰V *-pascal OSErr UTCheckVolRefNum(short vRefNum);
° d ONLN d£Ô H˚ w *vRefNum ° d ONLN d´Ô ¥˚n )l%Contains the volume reference number. ° d ONLN d—
Hˇ ( HUUTCheckVolRefNum will return noErr if a volume reference number is valid. The vRefNum ° d ONLN d' H%‰ * Tparameter must be a volume reference number, not a driver number, zero, or a working ° d ONLN d|% H1 À * directory reference number. ° d ONLN dòE TQ ê + Result codes ° d ONLN d•Q g] Ç + noErr ° d ONLN d´Q ˆ] ¸ )è0 ° d ONLN d≠Q]D )%No error ° d ONLN d∂] gi ñ (f grfNumErr ° d ONLN dø] Ïi ¸ )Ö-51 ° d ONLN d√]ifl )/(The volume reference number is not valid
° d ONLN dÏã Hö ⁄ (ñ HUTCheckPermission ö Föå
° d ONLN d˛ß H≥˝ *XUse UTCheckPermission to check the file access permission requested in response to _Open ° d ONLN dW≥ HøŒ * Ror _OpenRF if your foreign file system is using the Macintosh file system’s access ° d ONLN d™ø HÀ † * permission model. *)3- )
40 )&The Macintosh Volume Cache ˇb d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ,
Courier
° d ONLN d U ` a ( ^ `Fpascal OSErr UTCheckPermission(VCBPtr volCtrlBlockPtr, short *modByte, ° d ONLN d P a8 mº +ÿ unsigned long fileNum, ° d ONLN d p m8 y¬ * ParmBlkPtr paramBlock);
° d ONLN d à Ñ ` ê ´ ( ç `volCtrlBlockPtr ° d ONLN d ò Ñ Ã ê )lDContains a VCBPtr that specifies the volume the file to be opened is ° d ONLN d › ê Ã ú ‹ * on. ° d ONLN d · § ` ∞ ã ( ≠ `modByte ° d ONLN d È § Ã ∞ )lFContains a pointer to a short. On input, the field referred to by this ° d ONLN d0 ∞ Ã º * Dparameter contains the values your file system plans to put into the ° d ONLN du º Ã »
* EfcbFlags (in the high byte) and fcbTypByt (in the low byte) fields in ° d ONLN dª » Ã ‘ * Athe FCB. On output, UTCheckPermission places the corrected values ° d ONLN d˝ ‘ Ã ‡ * Hfor fcbFlags and fcbTypByt into the field referred to by this parameter. ° d ONLN dF Ë ` Ù á ( Ò `fileNum ° d ONLN dN Ë Ã Ù› )l<Contains a file number that specifies the file to be opened. ° d ONLN dã ¸ ` ô ( `
paramBlock ° d ONLN dñ ¸ Ã )lCContains a pointer to the parameter block used to make the _Open or ° d ONLN d⁄ Ã * _Open request. ° d ONLN dÈ& `2 (/ `YUTCheckPermission will check the file access permission requested in response to _Open or ° d ONLN dC2 `> * [_OpenRF to see if it is possible using the Macintosh file system’s access permission model. ° d ONLN düJ `V *^Before making this call, the foreign file system must determine what file number the open file ° d ONLN d˛V `b * Pwill have. The file number along with the VCBPtr will allow UTCheckPermission to ° d ONLN dOb `n
* ]determine if the requested access permission will conflict with any other access paths to the ° d ONLN d≠n `z s * file. ° d ONLN d≥Ü `í *YThe foreign file system must also determine what values will be put into the fcbFlags and ° d ONLN d
í `û˝ * RfcbTypByt fields of the FCBRec and supply those values to UTCheckPermission in the ° d ONLN d`û `™¬ * ImodByte parameterr; fcbFlags in the high byte, fcbTypByt in the low byte. ° d ONLN d™∂ `¬` *7The bits for the fcbFlags byte should be set as follows ° d ONLN d‚Œ l⁄ p + • ° d ONLN d‰Œ y⁄ )
XThe fcbWriteBit should be set if the requested permissions in the ioPermssn field of the ° d ONLN d=⁄ yÊÓ * Eparameter block are fsCurPerm, fsWrPerm, fsRdWrPerm, or fsRdWrShPerm. ° d ONLN dÉÚ l˛ p (˚ l• ° d ONLN dÖÚ y˛Œ )
EThe fcbResourceBit should be set if responding to an _OpenRF request. ° d ONLN dÀ
l p ( l• ° d ONLN dÕ
y )
WThe fcbSharedWriteBit should be set if the requested permissions in the ioPermssn field ° d ONLN d% y"F * (of the parameter block are fsRdWrShPerm. ° d ONLN dN. l: p (7 l• ° d ONLN dP. y: )
9The fcbFileLockedBit should be set if the file is locked. ° d ONLN däF `RX (O `8All other bits in in the fcbFlags field should be clear. ° d ONLN d√^ `j *YThe fcbTypByt (used for the file version by the MFS file system) must be zero because the ° d ONLN d j `v * WResource Manager, Segment Loader, and Standard File Package won’t operate on files with ° d ONLN duv `Ç ‡ * non-zero version numbers. ° d ONLN dèé `ö˜ *SIf UTCheckPermission returns noErr, then the value returned in modByte contains the ° d ONLN d„ö `¶ * Ycorrected values for fcbFlags and fcbTypByt and may be copied into the FCBRec for the new ° d ONLN d =¶ `≤ ô * access path. ° d ONLN d Jæ ` ¯ *TIf UTCheckPermission returns opWrErr, then the file reference number of the existing ° d ONLN d ü `÷Œ * Nexclusive-write path is returned in the ioRefNum field of the parameter block. +˛ The Macintosh Volume Cache )ß3- )
° d ONLN dƒ H+˚ *WUse UTCheckVolOffline to make sure a volume reference number is valid and the volume is ° d ONLN d + H7 i * online. ,
Courier
° d ONLN d$D HP\ *.pascal OSErr UTCheckVolOffline(short vRefNum);
° d ONLN dS[ Hg w *vRefNum ° d ONLN d[[ ¥gn )l%Contains the volume reference number. ° d ONLN dÅy HÖ (Ç H[UTCheckVolOffline will return noErr if a volume reference number is valid and the volume is ° d ONLN d›Ö Hë i * online. ° d ONLN d• T± ê + Result codes ° d ONLN dÚ± gΩ Ç + noErr ° d ONLN d¯± ˆΩ ¸ )è0 ° d ONLN d˙±ΩD )%No error ° d ONLN dΩ g… ñ (Δ grfNumErr ° d ONLN d Ω Ï… ¸ )Ö-51 ° d ONLN dΩ…fl )/(The volume reference number is not valid ° d ONLN d9… g’ • (“ g volOffLinErr ° d ONLN dF… Ï’ ¸ )Ö-53 ° d ONLN dJ…’Ä )/The volume is offline
° d ONLN d`˜ H Ï ( HUTCheckVolModifiable Få
° d ONLN du H { *>Use UTCheckVolModifiable to see if a volume can be written to.
° d ONLN d¥, H8n *1pascal OSErr UTCheckVolModifiable(short vRefNum);
. ( 2Ä The File System Utility Routines , Helvetica
° d ONLN d U ` d ( ` `UTCheckFileModifiable d ^ d§
° d ONLN d q ` }Ä *=Use UTCheckFileModifiable to see if a file can be written to. ,
Courier
° d ONLN d T ä ` ñû *5pascal OSErr UTCheckFileModifiable(short fileRefNum);
° d ONLN d ä ° ` ≠ ò *
fileRefNum ° d ONLN d ï ° à ≠r )l#Contains the file reference number. ° d ONLN d π ø ` À ( » `VUTCheckFileModifiable checks the volume’s vcbAtrb field in its VCB to determine if the ° d ONLN d À ` ◊ * Xvolume is locked by hardware or software and checks the file's fcbFlags in its FCBRec to ° d ONLN di ◊ ` „¯ * Xdetermine if the file can be written to through the access path specified by fileRefNum. ° d ONLN d¬ ˜ l ® + Result codes ° d ONLN dœ ö + noErr ° d ONLN d’ )è0 ° d ONLN d◊3\ )%No error ° d ONLN d‡ ¢ ( wPrErr ° d ONLN dÁ )Ö-44 ° d ONLN dÎ3˝ )/)The volume is write protected by hardware ° d ONLN d ' ¨ ($ vLckdErr ° d ONLN d ' )Ö-46 ° d ONLN d"3'” )/ The volume is locked by software ° d ONLN dC' 3 ¥ (0 wrPermErr ° d ONLN dM'3 )Ö-61 ° d ONLN dQ'33Ó )/(The file access path does not have write ° d ONLN d}33?g *
permission
° d ONLN dàa `p ⁄ (l `UTCheckDirBusy p ^p§
° d ONLN dó} `â∏ *FUse UTCheckDirBusy to see if a directory is an open working directory.
° d ONLN dfiñ `¢í *3pascal OSErr UTCheckDirBusy(VCBPtr volCtrlBlockPtr, ° d ONLN d¢Æì +µ unsigned long dirID);
° d ONLN d0π `≈ ´ (¬ `volCtrlBlockPtr ° d ONLN d@π Ã≈˙ )l@Contains a VCBPtr that specifies the volume the directory is on. ° d ONLN dÅÕ `Ÿ y (÷ `dirID ° d ONLN dáÕ ÃŸG )lContains the directory ID. ° d ONLN d¢Î `˜ı (Ù `SUTCheckDirBusy checks to see if the directory specified by dirID is an open working ° d ONLN dˆ˜ `^ * 5directory on the volume specified by volCtrlBlockPtr. ° d ONLN d, l# ® + Result codes ° d ONLN d9# / ö + noErr ° d ONLN d?#/ )è0 ° d ONLN dA#3/\ )%No error ° d ONLN dJ/ ; • (8 fBsyErr ° d ONLN dR/; )Ö-47 ° d ONLN dV/3;˝ )/*The directory is an open working directory
° d ONLN dÅ] `l ◊ (h `UTDetermineVol l ^l§
° d ONLN dêy `Ö *TUse UTDetermineVol to determine what volume a parameter block refers to and how that ° d ONLN dÂÖ `ë ÷ * determination was made.
° d ONLN d˝û `™Ê *Apascal OSErr UTDetermineVol(ParmBlkPtr paramBlock, short *status, ° d ONLN dG™∂á +µ short *moreMatches,
° d ONLN dZ™á∂ä )r
° d ONLN d[™ä∂‰ )short *vRefNum, ° d ONLN ds∂¬´ (øVCBPtr *volCtrlBlockPtr);
+I2The Macintosh Volume Cache )ß3- )
43 ˇ d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager ° d ONLN d U H a Å *,
paramBlock ° d ONLN d U ¥ aÆ )l6Contains a pointer to the parameter block to evaluate. ° d ONLN d B i H u c ( r Hstatus ° d ONLN d I i ¥ uÎ )lAContains a pointer to a short. UTDetermineVol places the decisive ° d ONLN d ã u ¥ ÅÒ * Bfactor used to determine what volume paramBlock refers to into the ° d ONLN d Œ Å ¥ çÁ * Dfield referred to by this parameter. The status values returned are: ° d ONLN d ç ÿ ô +$ dtmvError ° d ONLN d çD ôT )l= 0 ° d ONLN d# çh ôÎ )$could not determine volume ° d ONLN d? ô ÿ •+ ( ¢ ÿdtmvFullPathame ° d ONLN dO ôD •T )l= 1 ° d ONLN dS ôh •Ó )$determined by full pathname ° d ONLN dp • ÿ ±! ( Æ ÿ dtmvVRefNum ° d ONLN d| •D ±T )l= 2 ° d ONLN dÄ •h ±— )$determined by volume ° d ONLN dõ ±h Ω∫ * reference number ° d ONLN d≠ Ω ÿ …, ( Δ ÿ dtmvWDRefNum ° d ONLN d∫ ΩD …T )l= 3 ° d ONLN dæ Ωh …÷ )$determined by working ° d ONLN d⁄ …h ’Á * directory reference number ° d ONLN dˆ ’ ÿ ·" ( fi ÿ dtmvDriveNum ° d ONLN d ’D ·T )l= 4 ° d ONLN d ’h ·Ì )$determined by drive number ° d ONLN d# · ÿ Ì ( Í ÿ dtmvDefault ° d ONLN d0 ·D ÌT )l= 5 ° d ONLN d4 ·h ÌÙ )$ determined by default volume ° d ONLN dQ ı H á ( ˛ H moreMatches ° d ONLN d] ı ¥Ó )lCContains a pointer to a short. If the volume was determined by full ° d ONLN d° ¥
Û * =pathname and more than one mounted volume has the volume name ° d ONLN dfl
¥˝ * Apassed by paramBlock, UTDetermineVol places a non-zero value (the ° d ONLN d! ¥%ˇ * Hlength of the volume name) into the field referred to by this parameter. ° d ONLN dj% ¥1Ó * DThe value returned the field referred to by this parameter should be ° d ONLN dØ1 ¥=w * )ignored if status is not dtmvFullPathame. ° d ONLN dŸE HQ w (N HvRefNum ° d ONLN d·E ¥QË )l?Contains a pointer to a short. UTDetermineVol places the volume ° d ONLN d!Q ¥]– * >reference number into the field referred to by this parameter. ° d ONLN dae Hq ì (n HvolCtrlBlockPtr ° d ONLN dqe ¥q˝ )lCContains a pointer to an VCBPtr. UTDetermineVol places a pointer to ° d ONLN dµq ¥}ß * 5the VCB into the field referred to by this parameter. ° d ONLN dÎè Hõ‰ (ò HRUTDetermineVol uses the parameter block pointed to by paramBlock to determine what ° d ONLN d>õ HßÈ * Xvolume to use and returns the decisive factor used to determine the volume. The decisive ° d ONLN dóß H≥¯ * \factor used to determine the volume along with the other contents of the parameter block are ° d ONLN dÙ≥ Høj * Aused to find the file or directory the parameter block refers to. ° d ONLN d6À H◊≤ *IUTDetermineVol determines the volume by searching in the following order: ° d ONLN dÄ„ TÔ Z + 1 ° d ONLN dÇ„ aÔË )
QFull pathname - This method is used if ioNamePtr is not NULL and points to a full ° d ONLN d‘Ô a˚Ú * Wpathname (see Inside Macintosh: Files for the definition of a full pathname). The first ° d ONLN d,˚ a˘ * Ucomponent of the pathname pointed to by the ioNamePtr field in the parameter block is ° d ONLN dÇ aÒ * Oused as the volume name and UTDetermineVol attempts to find the volume by name. ° d ONLN d“ T+ Z (( T2 ° d ONLN d‘ a+Ù )
RReference number - The ioVRefNum field in the parameter block is used to determine ° d ONLN d'+ a7 * Tthe volume. If ioVRefNum is zero, UTDetermineVol attempts to find the default volume ° d ONLN d|7 aC * W(if the default volume is set up). If ioVRefNum is positive, UTDetermineVol attempts to ° d ONLN d‘C aOÎ * Ofind the volume by drive number. If ioVRefNum is negative, UTDetermineVol first ° d ONLN d $O a[Œ * Nattempts to find the volume by volume reference number and it that fails, then ° d ONLN d s[ agÒ * PUTDetermineVol attempts to find the volume by working directory reference number ,
Zapf Dingbats
° d ONLN d ≈s T _ (} Ts ° d ONLN d «t fÄ ö )Warning: ° d ONLN d œt öÄÈ )4C The PBGetCatInfo and PBGetFInfo File Manager calls do not use the ° d ONLN d
Ä få‡ (â fPioNamePtr field in a parameter block as an input when the ioFDirIndex field in a ° d ONLN d
då fò‚ * Nparameter block is non-zero. Before calling UTDetermineVol in these cases, you ° d ONLN d
≥ò f§∞ * Bmust save the value of ioNamePtr and set ioNamePtr to NULL so that ° d ONLN d
ˆ§ f∞Ë * OUTDetermineVol will not attempt to determine the volume by full pathname. After ° d ONLN d F∞ fºÃ * Jcalling UTDetermineVol, you must restore the original value in ioNamePtr.
° d ONLN d ê≤ê‘ (πÃs
(Ò H3- )
44 )&The Macintosh Volume Cache ˇ ∞ d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ° d ONLN d U ` a ( ^ `XIf the volume cannot be determined, UTDetermineVol will fail with paramErr and the field ° d ONLN d Y a ` mw * =referred to by the status parameter will be set to dtmvError. ° d ONLN d ó Å l ç ® + Result codes ° d ONLN d § ç ô ö + noErr ° d ONLN d ™ ç ô )è0 ° d ONLN d ¨ ç3 ô\ )%No error ° d ONLN d µ ô • ´ ( ¢ paramErr ° d ONLN d æ ô • )Ö-50 ° d ONLN d ¬ ô3 •Î )/'The parameter block does not refer to a ° d ONLN d Ì •3 ±Ç * mounted volume , Helvetica
° d ONLN d ¸ ” ` ‚ Ë ( fi `UTParsePathname ‚ ^ ‚§
° d ONLN d Ô ` ˚ *\Use UTParsePathname to detemine if a pathname is valid, if the pathname is a partial or full ° d ONLN di ˚ `Ω * Hpathname, and the volume name length if the pathname is a full pathname. ,
volNamelength ° d ONLN d+ Ã7˚ )lBContains a pointer to a short. If the pathname is a full pathname, ° d ONLN dJ7 ÃC * CUTParsePathname places the length of the volume name into the field ° d ONLN déC ÃO * Ereferred to by this parameter. If the pathname is a partial pathname, ° d ONLN d‘O Ã[ * >UTParsePathname places zero into the field referred to by this ° d ONLN d[ Ãg ˛ *
parameter. ° d ONLN d o `{ á (x `namePtr ° d ONLN d&o Ã{˙ )lBContains a pointer to a Pascal string that specifies the pathname. ° d ONLN diç `ô (ñ `VUTParsePathname determines if namePtr points to a valid pathname, if the pathname is a ° d ONLN d¿ô `• * \partial or full pathname, and the volume name length if the pathname is a full pathname. See ° d ONLN d • `± * [Inside Macintosh: Files for the definition of a full and partial pathnames. UTParsePathname ° d ONLN dy± `Ω∑ * Fcannot parse pathnames with more than 31 consecutive colon separators. ° d ONLN d¿— l› ® + Result codes ° d ONLN dÕ› È ö + noErr ° d ONLN d”›È )è0 ° d ONLN d’›3È\ )%No error ° d ONLN dfiÈ ı ± (Ú bdNamErr ° d ONLN dÁÈı )Ö-37 ° d ONLN dÎÈ3ı )/)namePtr is NULL, namePtr points to a zero ° d ONLN dı3 * 0length string, the pathname doesn’t have correct ° d ONLN dL3
ÿ * !syntax, or pathname has more than ° d ONLN dq
° d ONLN dÎp `|‘ *>pascal OSErr UTGetPathComponentName(ParsePathRecPtr parseRec);
° d ONLN d*á `ì ã *parseRec ° d ONLN d3á Ãì~ )l%Contains a pointer to a ParsePathRec. +íaThe Macintosh Volume Cache )ß3- )
45 ˇ
d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager ° d ONLN d i T u á + @parseRec , Symbol ° d ONLN d u T Ü ` *Æ ° d ONLN d y g Ö é )namePtr ° d ONLN d y ÿ Ö )q StringPtr ° d ONLN d y; Ö¯ )c*Contains a pointer to a Pascal string that ° d ONLN d L Ü; íß *
contains the pathname. ° d ONLN d c í T £ ` ( ü TÆ ° d ONLN d e ñ g ¢ ò ) startOffset ° d ONLN d q ñ ÿ ¢ )qshort ° d ONLN d w ñ; ¢Í )c%Contains the offset into the pathname ° d ONLN d ° £; ØÓ *
&where the parsing will begin. Offset 0 ° d ONLN d à Ø; ªÿ * %(not 1) is the first character of the ° d ONLN d ˆ ª; «l * pathname. ° d ONLN d « T ÿ ` ( ‘ T¨ ° d ONLN d À g ◊ º )componentLength ° d ONLN d À ÿ ◊ )qshort ° d ONLN d À; ◊ı )c!UTGetPathComponentName places the ° d ONLN d> ÿ; ‰Ú *
(length of the component into this field. ° d ONLN dg ‰ T ı ` ( Ò T¨ ° d ONLN di Ë g Ù õ )moreName ° d ONLN dr Ë ÿ Ù )qshort ° d ONLN dx Ë; ÙÏ )c'If there is no more pathname left after ° d ONLN d§ ı;ı *
!the parse, UTGetPathComponentName ° d ONLN d ;
* )places zero into this field; otherwise, a ° d ONLN d¯
;Ú * )non-zero value is placed into this field. ° d ONLN d" T* ` (& T¨ ° d ONLN d$ g) Æ )foundDelimiter ° d ONLN d3 ÿ) )qshort ° d ONLN d9 ;)Ì )c'If parsing stops because a delimiter (a ° d ONLN de*;6¥ *
colon character) is found, ° d ONLN dÑ6;BÏ * UTGetPathComponentName places a ° d ONLN d®B;N≈ * non-zero value into this field; ° d ONLN dÃN;Zı * *otherwise, zero is placed into this field. ° d ONLN d˜j Hvˆ (s HSUTGetPathComponentName parses a pathname to get the individual components that make ° d ONLN dKv HÇ ô * up the pathname. ° d ONLN d\é Hö˘ *TThe namePtr field in the ParsePathRec passed to UTGetPathComponentName must point to ° d ONLN d±ö H¶ä * Fthe pathname to parse. The startOffset field in the ParsePathRec tells ° d ONLN d¯¶ H≤ø * GUTGetPathComponentName where to start looking for a pathname component. ° d ONLN d@æ H ◊ *PUTGetPathComponentName returns the length of the component at startOffset in the ° d ONLN dë H÷‡ * VcomponentLength field of the ParsePathRec, indicates if the parse found the end of the ° d ONLN dË÷ H‚Ê * Vpathname in the moreName field of the ParsePathRec, and indicates if the parse stopped ° d ONLN d?‚ HÓ * (because a delimiter character was found. ° d ONLN dh T ê + Result codes ° d ONLN du g Ç + noErr ° d ONLN d{ ˆ ¸ )è0 ° d ONLN d}D )%No error ° d ONLN dÜ g& ô (# gbdNamErr ° d ONLN dè Ï& ¸ )Ö-37 ° d ONLN dì&È )/)namePtr is NULL, namePtr points to a zero ° d ONLN d¿&2˝ * 0length string, the pathname doesn’t have correct ° d ONLN dÙ2>¿ * !syntax, or pathname has more than ° d ONLN d>J± * 31 consecutive colon separators , Helvetica
° d ONLN d:l H{ û (w H
UTGetBlock { F{å
° d ONLN dEà Hîí *BUse UTGetBlock to get a cache block in the Macintosh volume cache. ,
Courier
° d ONLN dà° H≠ò *8pascal OSErr UTGetBlock(short refNum, void *log2PhyProc, ° d ONLN d»≠ flπi +ó unsigned long blockNum,
° d ONLN dfl≠iπl )ä
° d ONLN d‡≠lπΔ )short gbOption, ° d ONLN d˜π fl≈- (¬ fl
)lCContains the get block options. The option values you can pass are: ° d ONLN d[ µ ¡ +$ gbDefault ° d ONLN de µ8 ¡˝ )H+read from disk if block is not found in the ° d ONLN dï ¡8 ÕR * cache ° d ONLN dú Õ Ÿ ( ÷ gbRead ° d ONLN d£ Õ8 Ÿ˛ )H)always read block from disk (forced read) ° d ONLN dŒ Ÿ  ( ‚ gbExist ° d ONLN d÷ Ÿ8 Â
)H1get block only if it is already in the cache as a ° d ONLN d Â8 Ò * released block. ° d ONLN d Ò ˝# ( ˙ gbNoRead ° d ONLN d& Ò8 ˝¸ )H-do not read block if it is not already in the ° d ONLN dX ˝8 R * cache ° d ONLN d_ ( gbRelease ° d ONLN di 8 )H,this option can be added to any of the other ° d ONLN dö8! * *gbOptions to release the block immediately ° d ONLN d…!8-y * after getting it ° d ONLN d⁄5 `A } (> `buffer ° d ONLN d·5 ÃA )lDContains a pointer to a Ptr. UTGetBlock places the memory address of ° d ONLN d&A ÃMfi * =the cache block into the field referred to by this parameter. ° d ONLN dd_ `k (h `ZUTGetBlock gets a cache block in the Macintosh volume cache and returns the address of the ° d ONLN døk `w * Ycache block in the buffer parameter. If refNum is a volume reference number, the blockNum ° d ONLN dw `É * Yis the physical block on the volume. If refNum is a file reference number, then GetBlock ° d ONLN dsÉ `è * \calls the logical to physical routine to map blockNum, the logical file block, to a physical ° d ONLN d–è `õ ƒ * block on the volume. ° d ONLN dÂß `≥¿ *HUTGetBlock lets you specify several options with the gbOption parameter: ° d ONLN d.ø lÀ p + • ° d ONLN d0ø yÀ )
WgbDefault should be used to get a disk block from the cache if it’s in the cache, or to ° d ONLN dàÀ y◊z * ;bring a disk block into the cache if it isn’t in the cache. ° d ONLN dƒ„ lÔ p (Ï l• ° d ONLN dΔ„ yÔ )
RgbRead should be used to force a block to be read from from the disk. For example, ° d ONLN dÔ y˚ * Tyou’d use the gbRead option when handling a _Read call where the read-verify mode is ° d ONLN dn˚ y Ê * requested by the caller. ° d ONLN dá l p ( l• ° d ONLN dâ y ˘ )
NgbNoRead should be used to get a cache block who’s contents will be completely ° d ONLN dÿ y+ ≥ * overwritten. ° d ONLN dÂ7 lC p (@ l• ° d ONLN dÁ7 yC )
WgbExist should be used for getting a disk block which should already be in the cache as ° d ONLN d?C yO€ * Na released block. A free cache blocks is not found if gbExist is specified. If ° d ONLN déO y[Ú * KUTGetBlock with the gbExists option fails, use UTBlockInFQHashP to see if a ° d ONLN d⁄[ yg * Wphysical block on the volume is in a free cache block in the Macintosh volume cache and ° d ONLN d2g ysj * 2if so, retry UTGetBlock with the gbDefault option. ° d ONLN de lã p (à l• ° d ONLN dg yã )
OgbRelease can be added to any of the other gbOptions to release the cache block ° d ONLN d∑ã yó÷ * Mimmediately after getting it. This saves the step of releasing the block with ° d ONLN d ó y£ * NUTReleaseBlock when you know you won’t be making another call to the Macintosh ° d ONLN d T£ yØ˛ * PVolume Cache (which could reuse the cache block) before the cache block is used. +ÂEThe Macintosh Volume Cache )ß3- )
47 ˇ
Ó d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager ° d ONLN d a T m Ø + 8Important note: ° d ONLN d a Ø m )[CUTGetBlock can potentially return an internal positive error result ° d ONLN d T m T yfl ( v TVcode. Because the file system should never return a positive result, your foreign file ° d ONLN d ´ y T Ö” * Ssystem should return ioErr if it cannot recover gracefully from one of the positive ° d ONLN d ˇ Ö T ë ë * error results. ,
Zapf Dingbats
° d ONLN d £ T Ø _ * s ° d ONLN d § f ∞ ö )Warning: ° d ONLN d § ö ∞È )4E UTGetBlock may only be called from a foreign file system handling a ° d ONLN d^ ∞ f ºÕ ( π fIrequest through its HFSCIProc. Attempts to call UTGetBlock outside of the ° d ONLN d® º f »c * 4context of the HFSCIProc will cause a system crash.
° d ONLN d‹ æc «k )˝s
° d ONLN dfi ‚ T Ó ê ( Î T Result codes ° d ONLN dÎ Ó g ˙ Ç + noErr ° d ONLN dÒ Ó ˆ ˙ ¸ )è0 ° d ONLN dÛ Ó ˙D )%No error ° d ONLN d¸ ˙ g ì ( gchNoBuf ° d ONLN d ˙ ˆ ¸ )è1 ° d ONLN d ˙˜ )%1Cache internal error - no free cache buffers (all ° d ONLN d;G * reserved) ° d ONLN dE g è ( gchInUse ° d ONLN dM ˆ ¸ )è2 ° d ONLN dO ◊ )%)Cache internal error - requested block is ° d ONLN d| *C * reserved ° d ONLN dÖ* g6 † (3 g
° d ONLN d}∞ HºN *5Use UTReleaseBlock to release a reserved cache block. ,
Courier
° d ONLN d≥… H’ò *8pascal OSErr UTReleaseBlock(Ptr buffer, short rbOption);
° d ONLN dχ HÏ e *buffer ° d ONLN dÛ‡ ¥Ïî )l1Contains a pointer to the cache block to release. ° d ONLN d%Ù H r (˝ HrbOption ° d ONLN d.Ù ¥ )lBContains the release block options. The option values you can pass ° d ONLN dq ¥ ≈ * are: ° d ONLN dw ÿ +$ rbDefault ° d ONLN dÅ ã )Hrelease the cache block ° d ONLN dö ÿ$ ¸ (! ÿrbWrite ° d ONLN d¢ $Õ )H&release, write the cache block to disk ° d ONLN dÕ$ 0 * .(forced write) - this will also mark the cache ° d ONLN d 0 <U * block clean ° d ONLN d
< ÿH ˝ (E ÿrbTrash ° d ONLN d< H® )H mark the cache block trashed ° d ONLN d3H ÿT ˙ (Q ÿrbDirty ° d ONLN d;H T” )H&release and mark the cache block dirty ° d ONLN dfT `j * (deferred write) ° d ONLN dx` ÿl ˜ (i ÿrbFree ° d ONLN dÄ` lò )Hmark the cache block free ° d ONLN dö~ HäÍ (á HWUTReleaseBlock releases the reserved cache block specified in the buffer parameter. The ° d ONLN dÚä HñÛ * XrbOption parameter also allows UTReleaseBlock to write the cache block to disk, mark the ° d ONLN dKñ H¢v * Bcache block dirty, free the cache block, or trash the cache block. *R3- )
48 )&The Macintosh Volume Cache ˇp d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ° d ONLN d a l m « ( j lImportant note: ° d ONLN d a « mÛ )[@UTReleaseBlock can potentially return an internal positive error ° d ONLN d Q m l y ( v lXresult code. Because the file system should never return a positive result, your foreign ° d ONLN d ™ y l Öˆ * Wfile system should return ioErr if it cannot recover gracefully from the positive error ° d ONLN d Ö l ë ä * result. ,
Zapf Dingbats
° d ONLN d
£ l Ø w * s ° d ONLN d § ~ ∞ ≤ )Warning: ° d ONLN d § ≤ ∞‡ )4> UTReleaseBlock may only be called from a foreign file system ° d ONLN dS ∞ ~ ºÈ ( π ~Ihandling a request through its HFSCIProc. Attempts to call UTReleaseBlock ° d ONLN dù º ~ »æ * Coutside of the context of the HFSCIProc will cause a system crash.
° d ONLN d‡ ææ «Δ ( ≈æs
° d ONLN d‚ ‚ l Ó ® ( Î l Result codes ° d ONLN dÔ Ó ˙ ö + noErr ° d ONLN dı Ó ˙ )è0 ° d ONLN d˜ Ó3 ˙\ )%No error ° d ONLN d ˙ π (
chNotInUse ° d ONLN d ˙ )è1 ° d ONLN d
˙3 )%/Cache internal error - block being released was ° d ONLN d@3a *
not in use ° d ONLN dK ó ( ioErr ° d ONLN dQ )Ö-36 ° d ONLN dU3 Ò )/)Device I/O error (only if rbWrite option) ° d ONLN d * ¨ (' offLinErr ° d ONLN dâ * )Ö-65 ° d ONLN dç 3*˝ )/+Device was offline (only if rbWrite option) ° d ONLN dπ* 6 Í (3 notEnoughMemoryErr ° d ONLN dÃ* ˛6 )-620 ° d ONLN d—*36Î )5#VM was not able to hold down enough ° d ONLN d¯63Bˆ * (physical memory (only if rbWrite option) , Helvetica
° d ONLN d!d `s À (o ` UTFlushCache s ^s§
° d ONLN d.Ä `åÁ *RUse UTFlushCache to flush all dirty cache blocks associated with a file or volume. ,
Courier
° d ONLN dÅô `•∞ *8pascal OSErr UTFlushCache(short refNum, short fcOption);
° d ONLN d∫∞ `º Ö *refNum ° d ONLN d¡∞ ú• )l-Contains the file or volume reference number. ° d ONLN dÔƒ `– â (Õ `fcOption ° d ONLN d¯ƒ Ö )lEContains the flush block options. The option values you can pass are: ° d ONLN d?– ‹ +$ fcDefault ° d ONLN dI–8‹† )Hflush the cache blocks ° d ONLN da‹ Ë ( fcTrash ° d ONLN di‹8Ë )H,mark the cache blocks trashed after flushing ° d ONLN döË8ÙO * them ° d ONLN d†Ù (˝ fcFree ° d ONLN d®Ù8 ˜ )H)mark the cache blocks free after flushing ° d ONLN d÷ 8 O * them ° d ONLN d€ `*Û (' `UUTFlushCache flushes all dirty blocks associated with the file or volume specified by ° d ONLN d1* `6 * ZrefNum. The fcOption parameter also allows UTFlushCache to free the cache blocks, or trash ° d ONLN då6 `B
* %the cache blocks after flushing them. ° d ONLN d≤N lZ è + Note: ° d ONLN d∏N èZÚ )#KWhen the fcTrash or fcFree option is used, all cache blocks associated with ° d ONLN dZ lf„ (c lSthe file or volume are trashed or freed - not just those blocks that were dirty and ° d ONLN dXf lr ì * flushed.
. +H2 Guide to the File System Manager ° d ONLN d U T a ê + , Result codes ° d ONLN d
a g m Ç + noErr ° d ONLN d a ˆ m ¸ )è0 ° d ONLN d a mD )%No error , Helvetica
° d ONLN d è H û £ ( ö H UTMarkDirty û F ûå
° d ONLN d * ´ H ∑% *,Use UTMarkDirty to mark a cache block dirty. ,
Courier
° d ONLN d W ƒ H –& *%pascal OSErr UTMarkDirty(Ptr buffer);
° d ONLN d } € H Á e *buffer ° d ONLN d Ñ € ¥ Á• )l4Contains a pointer to the cache block to mark dirty. ° d ONLN d π ˘ H> ( H2UTMarkDirty marks the specified cache block dirty. ° d ONLN d Ï T% ê + Result codes ° d ONLN d ˘% g1 Ç + noErr ° d ONLN d ˇ% ˆ1 ¸ )è0 ° d ONLN d%1D )%No error
° d ONLN d
S Hb Õ (^ HUTTrashVolBlocks b Fbå
° d ONLN do H{˜ *XUse UTTrashVolBlocks to trash all file and volume cache blocks associated with a volume.
° d ONLN dtà Hîå *6pascal OSErr UTTrashVolBlocks(VCBPtr volCtrlBlockPtr);
° d ONLN d´ü H´ ì *volCtrlBlockPtr ° d ONLN dªü ¥´ä )l,Contains a VCBPtr that specifies the volume. ° d ONLN dËΩ H…‰ (Δ HTUTTrashVolBlocks trashes all file and volume cache blocks associated with the volume ° d ONLN d=… H’„ * Yspecified by volCtrlBlockPtr. That includes all released blocks and all free blocks. This ° d ONLN dó’ H·l * ;routine must be used when a volume is unmounted or ejected. ° d ONLN d”ı T ê + Result codes ° d ONLN d‡ g
Ç + noErr ° d ONLN dÊ ˆ
¸ )è0 ° d ONLN dË
D )%No error
° d ONLN dÒ/ H> — (: HUTTrashFileBlocks > F>å
° d ONLN dK HWò *GUse UTTrashFileBlocks to trash all cache blocks associated with a file.
° d ONLN dKd Hpå *6pascal OSErr UTTrashFileBlocks(VCBPtr volCtrlBlockPtr, ° d ONLN dãp |§ +ÿ unsigned long fileNum)
° d ONLN d¢á Hì ì (ê HvolCtrlBlockPtr ° d ONLN d≤á ¥ì« )l;Contains a VCBPtr that specifies the volume the file is on. ° d ONLN dÓõ Hß o (§ HfileNum ° d ONLN dˆõ ¥ßG )l Contains the file’s file number. ° d ONLN dπ H≈˙ (¬ H[UTTrashFileBlocks trashes all cache blocks associated with the file specified by fileNum on ° d ONLN ds≈ H—ˇ * _the volume specified by volCtrlBlockPtr. This routine is typically used when a file is deleted. *#3- )
50 )&The Macintosh Volume Cache ˇ d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ° d ONLN d U l a ® ( ^ l Result codes ° d ONLN d
a m ö + noErr ° d ONLN d a m )è0 ° d ONLN d a3 m\ )%No error , Helvetica
° d ONLN d è ` û Œ ( ö `
UTTrashBlocks û ^ û§
° d ONLN d , ´ ` ∑‰ *RUse UTTrashBlocks to trash or free a range of cache blocks associated with a file. ,
Courier
° d ONLN d ƒ ` –™ *7pascal OSErr UTTrashBlocks(unsigned long beginPosition, ° d ONLN d ø – ‹• +µ unsigned long byteCount, ° d ONLN d ‡ ‹ Ë * )VCBPtr volCtrlBlockPtr, short fileRefNum, ° d ONLN d Ë Ùo * short tbOption)
° d ONLN d" ˇ ` ° ( `
beginPosition ° d ONLN d0 ˇ à „ )l<Contains the beginning byte position of the blocks to trash. ° d ONLN dm î * .beginPosition must be a multiple of 512 bytes. ° d ONLN dú `+ ë (( ` byteCount ° d ONLN d¶ Ã+ )lCContains the number of bytes to trash. byteCount must be a multiple ° d ONLN dÍ+ Ã7 *
of 512 bytes. ° d ONLN d¯? `K ´ (H `volCtrlBlockPtr ° d ONLN d? ÃKfl )l;Contains a VCBPtr that specifies the volume the file is on. ° d ONLN dDS `_ ò (\ `
° d ONLN d+ `+ *RUse UTCacheReadIP to read a consecutive number of blocks into the caller’s buffer.
° d ONLN d~8 `Dn *-pascal OSErr UTCacheReadIP(void *log2PhyProc, ° d ONLN d¥DP∑ +µ unsigned long filePosition, ° d ONLN dÿP\œ * Ptr ioBuffer, short fileRefNum, ° d ONLN d \hü * unsigned long reqCount, ° d ONLN d ht• * unsigned long *actCount, ° d ONLN dAtÄá * short cacheOption);
° d ONLN dUã `ó û (î ` log2PhyProc ° d ONLN daã ÃóÎ )l>Contains a pointer to the logical to physical mapping routine. ° d ONLN d†ü `´ ñ (® ` filePosition ° d ONLN d≠ü ô )lIContains the position in bytes to start reading from. This must fall on a ° d ONLN d˜´ Ã∑¢ * -512-byte boundary (i.e., 0, 512, 1024, etc.). ° d ONLN d%ø `À à (» `ioBuffer ° d ONLN d.ø ÃÀÈ )l>Contains a pointer to data buffer where the data will be read. +í)The Macintosh Volume Cache )ß3- )
51 ˇ& d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager ° d ONLN d U H a Ä *,
fileRefNum ° d ONLN d U ¥ aZ )l#Contains the file reference number. ° d ONLN d / i H u t ( r HreqCount ° d ONLN d 8 i ¥ u˘ )lDContains the number of bytes to read. This must be a multiple of 512 ° d ONLN d } u ¥ Å — * bytes. ° d ONLN d Ñ â H ï r ( í HactCount ° d ONLN d ç â ¥ ïÚ )l@Contains a pointer to an unsigned long. UTCacheReadIP places the ° d ONLN d Œ ï ¥ °¸ * Hactual number of bytes read into the field referred to by this parameter ° d ONLN d ° ¥ ≠ ∏ * . ° d ONLN d µ H ¡ Ç ( æ H cacheOption ° d ONLN d% µ ¥ ¡” )l=Contains the cache options. The valid bits in the cacheOption ° d ONLN dc ¡ ¥ Õ ˆ * parameter are: ° d ONLN ds Õ ÿ Ÿ +$ noCache ° d ONLN d{ Õ Ÿ° )H please don’t cache this read ° d ONLN dô Ÿ ÿ  ( ‚ ÿrdVerify ° d ONLN d¢ Ÿ ÂÎ )H*always read blocks from disk (forced read) ° d ONLN dÕ ˜ HÓ ( HXUTCacheReadIP lets you request a multiple-block read from a file through the file system ° d ONLN d& H¸ * Tcache mechanism. UTCacheReadIP always reads a contiguous range of blocks. The number ° d ONLN d{ H· * Vof contiguous blocks actually read is determined by the log2PhyProc and is returned in ° d ONLN d“ H' v * actCount. ° d ONLN d‹3 H?Ì *YThe cacheOption parameter lets you request that reads not be cached, or that reads always ° d ONLN d6? HKœ * Rcome from the disk. A foreign file system handling a _Read call can simply use the ° d ONLN dâK HWà * OioPosMode word from the caller’s parameter block for the cacheOption parameter. ° d ONLN dŸc To Ø + Important note: ° d ONLN dÈc Øo€ )[?UTCacheReadIP can potentially return an internal positive error ° d ONLN d)o T{Í (x TXresult code. Because the file system should never return a positive result, your foreign ° d ONLN dÇ{ Tá * Xfile system should return ioErr if it cannot recover gracefully from one of the positive ° d ONLN d€á Tì ë * error results. ,
Zapf Dingbats
° d ONLN dÍ• T± _ * s ° d ONLN d϶ f≤ ö )Warning: ° d ONLN dÙ¶ ö≤» )4= UTCacheReadIP may only be called from a foreign file system ° d ONLN d2≤ fæ— (ª fHhandling a request through its HFSCIProc. Attempts to call UTCacheReadIP ° d ONLN d{æ f ¶ * Coutside of the context of the HFSCIProc will cause a system crash.
° d ONLN d濶…Æ («¶s
° d ONLN d¿‰ T ê (Ì T Result codes ° d ONLN dÕ g¸ Ç + noErr ° d ONLN d” ˆ¸ ¸ )è0 ° d ONLN d’¸D )%No error ° d ONLN dfi¸ g ì ( gchNoBuf ° d ONLN dʸ ˆ ¸ )è1 ° d ONLN d˸˜ )%1Cache internal error - no free cache buffers (all ° d ONLN d G * reserved) ° d ONLN d' g è ( gchInUse ° d ONLN d/ ˆ ¸ )è2 ° d ONLN d1 ◊ )%)Cache internal error - requested block is ° d ONLN d^ ,C * reserved ° d ONLN dg, g8 † (5 g
° d ONLN d_≤ Hæ„ *TUse UTCacheWriteIP to write a consecutive number of blocks from the caller’s buffer. *63- )
52 )&The Macintosh Volume Cache ˇ à d ˇ ˇˇˇˇ d
d , Times
. ( 2Ä The File System Utility Routines ,
Courier
° d ONLN d U ` at ( ^ `.pascal OSErr UTCacheWriteIP(void *log2PhyProc, ° d ONLN d 7 a m +µ )unsigned long filePosition, Ptr ioBuffer, ° d ONLN d i m y * )short fileRefNum, unsigned long reqCount, ° d ONLN d õ y Ö• * unsigned long *actCount, ° d ONLN d º Ö ëá * short cacheOption);
° d ONLN d – ú ` ® û ( • ` log2PhyProc ° d ONLN d ‹ ú à ®Î )l>Contains a pointer to the logical to physical mapping routine. ° d ONLN d ∞ ` º ñ ( π ` filePosition ° d ONLN d( ∞ à º )lGContains the position in bytes to start writing to. This must fall on a ° d ONLN dp º à »¢ * -512-byte boundary (i.e., 0, 512, 1024, etc.). ° d ONLN dû – ` ‹ à ( Ÿ `ioBuffer ° d ONLN dß – à ‹√ )l6Contains a pointer to data buffer containing the data. ° d ONLN dfi ‰ ` ò ( Ì `
fileRefNum ° d ONLN dÈ ‰ Ã r )l#Contains the file reference number. ° d ONLN d
¯ ` å ( `reqCount ° d ONLN d ¯ à )lEContains the number of bytes to write. This must be a multiple of 512 ° d ONLN d\ Ã È * bytes. ° d ONLN dc `$ ä (! `actCount ° d ONLN dl Ã$ )lAContains a pointer to an unsigned long. UTCacheWriteIP places the ° d ONLN dÆ$ Ã0 * Aactual number of bytes written into the field referred to by this ° d ONLN d0 Ã< * parameter . ° d ONLN d¸D `P ö (M ` cacheOption ° d ONLN dD ÃPÎ )l=Contains the cache options. The valid bits in the cacheOption ° d ONLN dFP Ã\ * parameter are: ° d ONLN dV\ h +$ noCache ° d ONLN d^\8hΩ )H please don’t cache this write ° d ONLN d|z `ܲ (É `XUTCacheWriteIP lets you request a multiple-block write to a file through the file system ° d ONLN d’Ü `í * Vcache mechanism. UTCacheWriteIP always writes a contiguous range of blocks. The number ° d ONLN d,í `û * Yof contiguous blocks actually written is determined by the log2PhyProc and is returned in ° d ONLN dÜû `™ é * actCount. ° d ONLN dê∂ `¬ *[The cacheOption parameter lets you request that writes not be cached. A foreign file system ° d ONLN dϬ `Œ * Zhandling a _Write call can simply use the ioPosMode word from the caller’s parameter block ° d ONLN dGŒ `⁄ Ò * for the cacheOption parameter. ° d ONLN dfÊ lÚ « + Important note: ° d ONLN dvÊ «Úı )[@UTCacheWriteIP can potentially return an internal positive error ° d ONLN d∑Ú l˛ (˚ lXresult code. Because the file system should never return a positive result, your foreign ° d ONLN d˛ l
˝ * Xfile system should return ioErr if it cannot recover gracefully from one of the positive ° d ONLN di
° d ONLN dx( l4 w * s ° d ONLN dz) ~5 ≤ )Warning: ° d ONLN dÇ) ≤5‚ )4> UTCacheWriteIP may only be called from a foreign file system ° d ONLN d¡5 ~AÎ (> ~Ihandling a request through its HFSCIProc. Attempts to call UTCacheWriteIP ° d ONLN d A ~Mæ * Coutside of the context of the HFSCIProc will cause a system crash.
° d ONLN dNCæLΔ (Jæs
(Ò^The Macintosh Volume Cache )ß3- )
53 ˇ
6 d ˇ ˇˇˇˇ d
d , Times
. +H2 Guide to the File System Manager ° d ONLN d i T u ê + @ Result codes ° d ONLN d
u g Å Ç + noErr ° d ONLN d u ˆ Å ¸ )è0 ° d ONLN d u ÅD )%No error ° d ONLN d Å g ç ì ( ä gchNoBuf ° d ONLN d & Å ˆ ç ¸ )è1 ° d ONLN d ( Å ç˜ )%1Cache internal error - no free cache buffers (all ° d ONLN d ] ç ôG * reserved) ° d ONLN d g ô g • è ( ¢ gchInUse ° d ONLN d o ô ˆ • ¸ )è2 ° d ONLN d q ô •◊ )%)Cache internal error - requested block is ° d ONLN d û • ±C * reserved ° d ONLN d ß ± g Ω † ( ∫ g
° d ONLN d°7 HC˙ *YUse UTBlockInFQHashP to see if a physical block on the volume is in a free cache block in ° d ONLN d˚C HO — * the Macintosh volume cache. ,
Courier
° d ONLN d\ HhÏ *Fpascal OSErr UTBlockInFQHashP(short vRefNum, unsigned long diskBlock);
° d ONLN d^s H w *vRefNum ° d ONLN dfs ¥n )l%Contains the volume reference number. ° d ONLN dåá Hì x (ê H diskBlock ° d ONLN dñá ¥ì• )l1Contains the physical block number of the volume. ° d ONLN d»• H± (Æ H]UTBlockInFQHashP lets you check to see if the specified block is in a free cache block in the ° d ONLN d&± HΩÓ * UMacintosh volume cache. UTBlockInFQHashP returns noErr if the disk block data is in a ° d ONLN d|Ω H…˙ * _free cache block. A result of chNotfound indicates that the disk block is not in the free block ° d ONLN d‹… H’â * Equeue (although it may in the cache as a reserved or released block). ° d ONLN d"È Tı ê + Result codes ° d ONLN d/ı g Ç + noErr ° d ONLN d5ı ˆ ¸ )è0 ° d ONLN d7ıD )%No error ° d ONLN d@ g
† (
g
chNotfound ° d ONLN dK ˆ
¸ )è3 ° d ONLN dM
‚ )%)Requested block was not found in the free ° d ONLN dz
T * block queue (Ò H3- )
54 )&The Macintosh Volume Cache ˇ d ˇ ˇˇˇˇ d
d , Helvetica
. ° d ONLN d V ` h k +`d4 ° d ONLN d V Ñ h¯ )$!THE DISK INITIALIZATION COMPONENT Q ^ Q ° d ONLN d $ l Ñ ~ Û * INTERFACE ~ ^ ~ , Times
(Ú
4- )
1 ˇ
: d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager , Helvetica
° d ONLN d U H d Ú *-ABOUT THIS CHAPTER N F N g F g
° d ONLN d ~ H ä *'_This chapter describes the Disk Initialization Package component interface, the data structures ° d ONLN d s ä H ñ * _used by the Disk Initialization Package component interface, and the routines your foreign file ° d ONLN d ” ñ H ¢≠ * Ksystem must provide to the Disk Initialization Package component interface. ° d ONLN d Æ H ∫Ê *YTo use this chapter, you should be familiar with the information in the chapter “The File ° d ONLN dy ∫ H ΔK * 5System Manager” in this document, the information in ° d ONLN dÆ ∫K Δπ ( √KInside Macintosh: Files ° d ONLN d≈ ∫π ΔŒ )n, the ° d ONLN dÀ Δ H “ é ( œ Hinformation in ° d ONLN d⁄ Δ é “
)FInside Macintosh: Devices ° d ONLN dÛ Δ
“ı )|1, and the information in the Technical Note “What ° d ONLN d% “ H fi œ ( € HYour Sony Drives for You”.
° d ONLN d@ H˜ *3/ABOUT THE DISK INITIALIZATION PACKAGE COMPONENT ¸ F ¸ ° d ONLN dp H* † * INTERFACE - F-
° d ONLN dzD HPÙ *'[The Disk Initialization Package component interface allows a foreign file system to process ° d ONLN d÷P H\„ * ZDisk Initialization Package requests and allows a foreign file system to describe its disk ° d ONLN d1\ HhÌ * Zinitialization services to the File System Manager. Whenever a Disk Initialization Package ° d ONLN dåh HtÛ * [request is made, the File System Manager will call the foreign file system through the Disk ° d ONLN dËt HĈ * ]Initialization Package component interface to get additional information and request specific ° d ONLN dFÄ Hå m * actions.
° d ONLN dO± H¿Û *3/USING THE DISK INITIALIZATION PACKAGE COMPONENT ™ F™ ° d ONLN d… Hÿ † * INTERFACE € F€
° d ONLN dâÚ H˛ ∞ *'This section describes ° d ONLN d†
T X + • ° d ONLN d¢
av )
:the Disk Initialization Package Component Interface record ° d ONLN d›" T. X (+ T• ° d ONLN dfl" a.¸ )
Wthe Disk Initialization Package Component Interface request processing function and its ° d ONLN d7. a: ¥ * function selectors
° d ONLN dJR Ha˘ (] H:The Disk Initialization Package Component Interface Record a Fa
° d ONLN dÖn HzÊ *WThe Disk Initialization Package component interface record in an File System Descriptor ° d ONLN d›z HÜ * `record lets the foreign file system tell the Disk Initialization Package component interface how ° d ONLN d>Ü HíÎ * ^to dispatch Disk Initialization Package requests to the foreign file system. It tells the Disk ° d ONLN dùí HûÁ * ZInitialization Package component interface where the routine to handle Disk Initialization ° d ONLN d¯û H™ * YPackage requests is in memory, the maximum length of volume names the foreign file system ° d ONLN dR™ H∂ * ^can accept, and the disk block size of your foreign file system’s volume format. The data type ° d ONLN d±∂ H¬Ø * KDICIRec defines the Disk Initialization Package component interface record. *34- )
2 )&9Using the Disk Initialization Package Component Interface ˇ§ d ˇ ˇˇˇˇ d
d , Times
. ( 383The Disk Initialization Package Component Interface ,
* !formatting operation. This bit is ° d ONLN dîw†„ * maintained by the Disk ° d ONLN d †w¨€ * Initialization Package ° d ONLN d7¨w∏⁄ * component interface. ° d ONLN dL∏ à ‚ (¡ Ã1-15 ° d ONLN dR∏wƒß )´ Reserved. ° d ONLN d\ƒ Ö ÿ (Õ Ã16 ° d ONLN d_ƒ Á–G )diCIDoesSparingBit ° d ONLN drƒw–˚ )ê Set this bit if the foreign file ° d ONLN dñ–w‹ * system supports bad block disk ° d ONLN d∏‹wËû * sparing. ° d ONLN d¡Ë ÃÙ ÿ (Ò Ã17 ° d ONLN dƒË ÁÙd )diCIHasMultiVolTypesBit ° d ONLN d‹ËwÙ˚ )ê Set this bit if the foreign file ° d ONLN d Ùw
* system supports more than one ° d ONLN d! w µ * volume type. ° d ONLN d. à ÿ ( Ã18 ° d ONLN d1 Ár )diCIHasExtFormatParamsBit ° d ONLN dK w˚ )ê Set this bit if the foreign file ° d ONLN dow$ˇ * system uses extended format ° d ONLN dé$w0Æ * parameters. ° d ONLN dö0 Ã< Ë (9 Ã19-23 ° d ONLN d†0w<ß )´ Reserved. ° d ONLN d™< ÃH Ë (E Ã24-29 ° d ONLN d∞<wH )´ Reserved for the File System ° d ONLN d–HwT¿ * Manager’s use. ° d ONLN dflT Ã` ÿ (] Ã30 ° d ONLN d‚T Á`W )fsmComponentBusyBit ° d ONLN dˆTw`ˆ )êIf set, the FSM component ° d ONLN d`wl * interface is busy (i.e., one or ° d ONLN d6lwx * more requests are outstanding). ° d ONLN dYxwѸ * This bit is maintained by the ° d ONLN dzÑwê
* component and used by the File ° d ONLN dúêwú * System Manager to control the ° d ONLN dΩúw®Ó * use of the SetFSInfo File ° d ONLN d⁄®w¥ * System Manager service request. (Ú ÿ9Using the Disk Initialization Package Component Interface (Ú 4- )
° d ONLN d?' H6 (2 H;The Disk Initialization Package Component Interface Request ° d ONLN d{5 HD € *Processing Function D FD
° d ONLN dèQ H]˜ *ZThe Disk Initialization Package Component Interface request processing function pointed to ° d ONLN dÍ] HiŸ * Rby compInterfProc in a DICIRec is called by the File System Manager to handle Disk ° d ONLN d=i Hu˙ * \Initialization Package requests. The Disk Initialization Package Component Interface request ° d ONLN döu HÅ8 * 1processing function must have the following form. ,
Courier
° d ONLN dÃé Hö™ *;pascal OSErr DICIProc(short whatFunction, void *paramBlock, ° d ONLN dö fl¶W +ó void *fsdGlobalPtr);
° d ONLN d$± HΩ â (∫ H whatFunction ° d ONLN d1± ¥Ωˇ )lEContains a selector number which indicates what operation the foreign ° d ONLN dwΩ ¥…. * file system must perform. ° d ONLN dë— H› Å (⁄ H
paramBlock ° d ONLN dú— ¥›Œ )l<Contains a pointer to the parameter block passed to the Disk ° d ONLN dŸ› ¥È’ * =Initialization Package component interface request processing ° d ONLN dÈ ¥ıfl * Afunction. The contents of the parameter block are specific to the ° d ONLN dYı ¥& * selector number passed. ° d ONLN dq H Ö ( H fsdGlobalPtr ° d ONLN d~ ¥Í )lDContains a pointer to the foreign file system’s optional global data ° d ONLN d√ ¥! À * area. ° d ONLN d…3 H?Ó (< HZWhen the foreign file system’s DICIProc is called, it is passed a function selector number ° d ONLN d$? HK„ * Ywhich specifies the operation to perform, a pointer to a buffer containing any additional ° d ONLN d~K HW˜ * ]parameters needed to process the operation, and a pointer to the foreign file system’s global ° d ONLN d‹W Hcz * Bdata area. The currently defined messages are listed in Table 4-1. ° d ONLN d o H{ g *Table
° d ONLN d$p g{ i )
° d ONLN d%o i{ Å )4-1. ° d ONLN d*o ê{Œ )'BDisk Initialization Package Component Interface Function Selectors ° d ONLN dmÜ Hí x (è HMessage ° d ONLN duÜ ·í )ôPurpose F ° d ONLN d}û H™ u (ß HdiCILoad ° d ONLN dÜû –™ ÷ )à1 ° d ONLN dàû ‚™ˆ )=Load the disk initialization code and data resources (if they ° d ONLN dΔ™ ‚∂fl * 3are not loaded or purged) and make them unpurgable. (Ú H4- )
4 )&9Using the Disk Initialization Package Component Interface ˇ ¸ d ˇ ˇˇˇˇ d
d , Times
. ( 383The Disk Initialization Package Component Interface ° d ONLN d a ` m ò ( j `
° d ONLN dFÀ `◊ *aThe diCILoad function selector tells the foreign file system to load the disk initialization code ° d ONLN d®◊ `„Ò * Sand data resources (if they are not loaded or purged) and make them unpurgable. The ° d ONLN d¸„ `ÔÆ * EparamBlock parameter is not used with the diCILoad function selector. ° d ONLN dB l ® + Result codes ° d ONLN dO ö + noErr ° d ONLN dU )è0 ° d ONLN dW3\ )%No error ° d ONLN d` '
($ Qany of the result codes returned by the Resource Manager, GetFSInfo, or SetFSInfo
° d ONLN d≤C `R ∞ (N `
diCIUnload
° d ONLN dΩ] `i *^The diCIUnload function selector tells the foreign file system to make the disk initialization ° d ONLN d i `u· * Ocode and data resources purgable. The paramBlock parameter is not used with the ° d ONLN dlu `Å Ì * diCIUnload function selector. ° d ONLN däï l° ® + Result codes ° d ONLN dó° ≠ ö + noErr ° d ONLN dù°≠ )è0 ° d ONLN dü°3≠\ )%No error (Ú ÿ9Using the Disk Initialization Package Component Interface (Ú 4- )
5 ˇ¬ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager , Helvetica
° d ONLN d U H d ˝ *-diCIEvaluateSizeChoices
° d ONLN d o H {˙ *]The diCIEvaluateSizeChoices function selector allows a foreign file system to determine if it ° d ONLN d v { H á˚ * acan initialize a disk in the specified drive. If the disk drive can format disks in more than one ° d ONLN d ÿ á H ìÓ * ]size, the foreign file system indicates what sizes it can support and the preferred size. The ° d ONLN d6 ì H üt * <paramBlock parameter points to a DICIEvaluateSizeRec record. ° d ONLN ds ≥ T ø Õ + DICIEvaluateSizeRec , Symbol ° d ONLN dá ø T – ` *¨ ° d ONLN dâ √ g œ ∂ )defaultSizeIndex ° d ONLN dö √ Δ œ fi )_short ° d ONLN d† √ œ÷ )Q)The foreign file system returns the index ° d ONLN dŒ – ‹Ú *
.number of the preferred or default SizeListRec ° d ONLN d ‹ ˉ * 0in this field; the first SizeListRec is at index ° d ONLN d6 Ë ÙÓ * .position 1. If none of the SizeListRec records ° d ONLN di Ù Í * 0contain a valid size choice for the foreign file ° d ONLN dû v * system, return zero. ° d ONLN d≥ T ` ( TÆ ° d ONLN dµ g ± )numSizeEntries ° d ONLN dƒ Δ fi )_short ° d ONLN d Û )Q-Contains the number of SizeListRec records in ° d ONLN d¸ )∫ *
$the array pointed to by sizeListPtr. ° d ONLN d!) T: ` (6 TÆ ° d ONLN d#- g9 ¶ ) driveNumber ° d ONLN d/- Δ9 fi )_short ° d ONLN d5-9ò )QContains the drive number. ° d ONLN dP: TK ` (G TÆ ° d ONLN dR> gJ ô ) sizeListPtr ° d ONLN d^> ΔJ )_SizeListRecPtr ° d ONLN dm>JØ )Q!Contains a pointer to an array of ° d ONLN dìKWy *
SizeListRec records. ° d ONLN d®W Th ` (d TÆ ° d ONLN d™[ gg ó )
sectorSize ° d ONLN dµ[ Δg )_unsigned short ° d ONLN dƒ[g” )Q'Contains the number of bytes per sector ° d ONLN dht„ *
sizeListFlags ° d ONLN d!ÿ Δ‰ fi )_short ° d ONLN d'ÿ‰fl )Q-The foreign file system returns the size list ° d ONLN dYÂÒ¯ *
4flags in this field. All bits are currently reserved ° d ONLN díÒ˝8 * except: ° d ONLN dû˝ z + diCISizeListOKBit ° d ONLN d∞˝å Ó )lSet this bit if the size ° d ONLN d— åÒ * specified in sizeEntry ° d ONLN då!Ê * can be used by this ° d ONLN d !å-Ë * foreign file system. ° d ONLN d!- T> ` (: TÆ ° d ONLN d#1 g= ì ) sizeEntry ° d ONLN d-1 Δ= )_
FormatListRec ° d ONLN d;1=Ê )Q*Contains a FormatListRec which specifies a ° d ONLN dj>Jê *
possible size of the drive. ° d ONLN dÜZ HfP (c H8The sizeEntry field in a SizeListRec is a FormatListRec. ° d ONLN døz TÜ ß +
FormatListRec ° d ONLN dÕÜ Tó ` *Æ ° d ONLN dœä gñ ä )volSize ° d ONLN d◊ä Δñ )_
unsigned long ° d ONLN dÂäñŸ )Q*Contains the disk capacity in disk sectors ° d ONLN dó£„ *
+(sectors may not be the same size as blocks ° d ONLN dD£Øß * used by a foreign file system). (Ú H4- )
6 )&9Using the Disk Initialization Package Component Interface ˇæ d ˇ ˇˇˇˇ d
d , Times
. ( 383The Disk Initialization Package Component Interface , Symbol ° d ONLN d U l f x ( b lÆ ° d ONLN d Y e ∏ ) formatFlags ° d ONLN d Y fi e )_
SignedByte ° d ONLN d Y/ eˆ )Q+Contains the format flags, density bit, and ° d ONLN d I f/ r *
number of disk sides. The sides, ° d ONLN d n r/ ~Á * (sectorsPerTrack, and tracks are valid if ° d ONLN d õ ~/ ä * -diCIFmtFlagsValidBit is set. The current disk ° d ONLN d Õ ä/ ñ * ,has this format if diCIFmtFlagsCurrentBit is ° d ONLN d ˛ ñ/ ¢
* -set. The disk is double-density (.SONY driver ° d ONLN d0 ¢/ Æ
* -only) if diCIFmtFlagsDoubleDensityBit is set. ° d ONLN db Æ/ ∫
* .The low nibble of the byte contains the number ° d ONLN dï ∫/ Δo * of disk sides. ° d ONLN d® Δ l ◊ x ( ” lÆ ° d ONLN d™ ÷ À )sectorsPerTrack ° d ONLN d∫ fi ÷ )_
SignedByte ° d ONLN d≈ / ÷˚ )Q*Contains the average number of sectors per ° d ONLN dÙ ◊/ „J *
track. ° d ONLN d˚ „ l Ù x ( lÆ ° d ONLN d˝ Á Û õ )tracks ° d ONLN d Á fi Û$ )_unsigned short ° d ONLN d Á/ Ûÿ )Q#Contains the number of disk tracks. ° d ONLN d7 ` (
`YThe array of SizeListRec records is built from information obtained from the disk driver. ° d ONLN dë ` * YSpecifically, the File System Manager obtains the SizeListRec records by calling the disk ° d ONLN dÎ `( * \driver’s _Status function with csCode set to Return Format List (6). If the disk driver does ° d ONLN dH( `4˛ * Xnot support the Return Format List request, a single SizeListRec is constructed from the ° d ONLN d°4 `@ * 'information in the drive queue element. ° d ONLN d…L `X *ZThe foreign file system must index through the array of SizeListRec records. The number of ° d ONLN d$X `d * _elements in the array is indicated by numSizeEntries. If the foreign file system can format the ° d ONLN dÑd `p * _disk using the size specified by a particular SizeListRec, it sets the diCISizeListOKBit in the ° d ONLN d‰p `| * \SizeListRec’s sizeListFlags field. SizeListRec records usable by the foreign file system are ° d ONLN dA| `à≠ * Fshown in the Format pop-up menu in the disk initialization dialog box. ° d ONLN dàî `†˚ *VThe index of the preferred SizeListRec is returned in the DICIEvaluateSizeRec record’s ° d ONLN dfl† `¨ * ^defaultSizeIndex field where defaultSizeIndex is in the range 1 to numSizeEntries. This is the ° d ONLN d>¨ `∏¯ * Vmenu item shown in the Format pop-up menu in the disk initialization dialog box if the ° d ONLN dï∏ `ƒm * :current disk is already owned by this foreign file system. ° d ONLN d–ÿ l‰ ® + Result codes ° d ONLN d›‰ ö + noErr ° d ONLN d„‰ )è0 ° d ONLN d‰3\ )%No error , Helvetica
° d ONLN dÓ ` „ ( `diCIExtendedZero
° d ONLN dˇ& `2 *]The diCIExtendedZero function selector allows a foreign file system to initialize a disk. The ° d ONLN d]2 `>í * <paramBlock parameter points to a DICIExtendedZeroRec record. ° d ONLN döR l^ Î + DICIExtendedZeroRec ° d ONLN dÆ^ lo x *Æ ° d ONLN d∞b n æ ) driveNumber ° d ONLN dºb fin ˆ )_short ° d ONLN d¬b/n )Q-Contains the drive number of the device which ° d ONLN dÙo/{˘ *
*should be initialized with an empty volume ° d ONLN d#{/áâ * directory structure. ° d ONLN d8á lò x (î lÆ ° d ONLN d:ã ó ∏ )
volNamePtr ° d ONLN dEã fió )_ StringPtr ° d ONLN dOã/ó )Q.Contains a pointer to the name that the volume ° d ONLN dÇò/§~ *
should be given. ° d ONLN dì§ lµ x (± lÆ ° d ONLN dï® ¥ ë )fsid ° d ONLN dö® fi¥ ˆ )_short ° d ONLN d†®/¥– )Q#Contains the target file system ID. (Ú ÿ9Using the Disk Initialization Package Component Interface (Ú 4- )
7 ˇ⁄ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager , Symbol ° d ONLN d U T f ` + /Æ ° d ONLN d Y g e ¥ )volTypeSelector ° d ONLN d Y Δ e fi )_short ° d ONLN d Y eˆ )Q0Contains the volume type selector if the foreign ° d ONLN d M f r‚ *
)file system supports more than one volume ° d ONLN d { r ~÷ * 'type (diCIHasMultiVolTypesBit is set in ° d ONLN d ß ~ ä· * )the compInterfMask field of the DICIRec). ° d ONLN d — ä T õ ` ( ó TÆ ° d ONLN d ” é g ö ª )numDefectBlocks ° d ONLN d „ é Δ ö )_unsigned short ° d ONLN d Ú é ö‡ )Q)Contains the number of bad disk blocks or ° d ONLN d õ ßÒ *
,numDefectBlocks is not zero. For example, if ° d ONLN d˙ – ‹ı * .the volume size is 800K and your file system’s ° d ONLN d- ‹ ËÚ * /block size is 1024 bytes, then defectListSize = ° d ONLN da Ë ÙÍ * .100 (800 bits = 100 bytes) and the defect list ° d ONLN dî Ù ï * buffer is 100 bytes in size. ° d ONLN d± T ` (
TÆ ° d ONLN d≥ g £ )
defectListPtr ° d ONLN d¡ Δ ‘ )_Ptr ° d ONLN d≈‰ )Q/Contains a pointer to the defect list buffer if ° d ONLN d˘ ÿ *
'numDefectBlocks is not zero. The buffer ° d ONLN d% )ı * 0contains a bitmap of the disk blocks. A zero bit ° d ONLN dY)5Ì * ,means the block is good, and a one bit means ° d ONLN dä5AÌ * 0the block is defective. This buffer is allocated ° d ONLN døAM“ * )by the Disk initialization Package and is ° d ONLN dÌMYÙ * 1released by the Disk initialization Package after ° d ONLN d#Yeô * returning from this request. ° d ONLN d@e Tv ` (r TÆ ° d ONLN dBi gu ä )volSize ° d ONLN dJi Δu )_unsigned short ° d ONLN dYiuÚ )Q/Contains the size of the volume in disk sectors ° d ONLN dçvÇ„ *
+(sectors may not be the same size as blocks ° d ONLN dΩÇéß * used by a foreign file system). ° d ONLN d›é Tü ` (õ TÆ ° d ONLN dflí gû ó )
sectorSize ° d ONLN dÍí Δû )_unsigned short ° d ONLN d˘íûÍ )Q,Contains the number of bytes per disk sector ° d ONLN d*ü´„ *
+(sectors may not be the same size as blocks ° d ONLN dZ´∑ß * used by a foreign file system). ° d ONLN dz∑ T» ` (ƒ TÆ ° d ONLN d|ª g« ≥ )extendedInfoPtr ° d ONLN dåª Δ« ‘ )_Ptr ° d ONLN dêª«Ó )Q/Contains a pointer to the foreign file system’s ° d ONLN dƒ»‘Ω *
#extended formatting information (if ° d ONLN dÏ‘‡⁄ * 'diCIHasExtFormatParamsBit is set in the ° d ONLN d‡Ï * -compInterfMask field of the DICIRec), or nil. ° d ONLN dF¸ H£ ( HJThe foreign file system must initialize the disk specified by driveNumber. ° d ONLN dë H Ú *YIf the foreign file system has set diCIHasMultiVolTypesBit in the compInterfMask field of ° d ONLN dÎ H,¯ * \the DICIRec indicating that it supports multiple volume formats, the volume type selected is ° d ONLN dH, H8 • * in volTypeSelector. ° d ONLN d\D HPÊ *XIf the foreign file system has set diCIDoesSparingBit in the compInterfMask field of the ° d ONLN dµP H\ˇ * \DICIRec, it can use the information in numDefectBlocks, defectListSize, and defectListPtr to ° d ONLN d\ Hh … * perform bad block sparing. *ç4- )
8 )&9Using the Disk Initialization Package Component Interface ˇD d ˇ ˇˇˇˇ d
d , Times
. ( 383The Disk Initialization Package Component Interface ° d ONLN d i l u ® ( r l Result codes ° d ONLN d
/ `; *XThe diCIValidateVolName function selector allows a foreign file system to determine if a ° d ONLN dc; `G˛ * Qvolume name is valid. The paramBlock parameter points to a DICIValidateVolNameRec ° d ONLN dµG `S Ç * record. ° d ONLN dΩg ls ˇ + DICIValidateVolNameRec , Symbol ° d ONLN d‘s lÑ x *Æ ° d ONLN d÷w É § )theChar ° d ONLN dfiw fiÉ Ú )_char ° d ONLN d„w/ÉŒ )Q#Contains the character to validate. ° d ONLN dÑ lï x (ë l¨ ° d ONLN d à î ◊ )hasMessageBuffer ° d ONLN dà fiî )_Boolean ° d ONLN d"à/î
)Q2The foreign file system returns true in this field ° d ONLN dYï/° *
0if it is providing its own alert message when an ° d ONLN dé°/≠ * /illegal character is detected (messageBufferPtr ° d ONLN d¬≠/π} * must not be nil). ° d ONLN d‘π l x (Δ lÆ ° d ONLN d÷Ω … ∞ )
charOffset ° d ONLN d·Ω fi… ˆ )_short ° d ONLN dÁΩ/… )Q.Contains the position of the current character ° d ONLN d /÷‘ *
'(the first character is at position 1). ° d ONLN dB÷ lÁ y („ l´ ° d ONLN dD⁄ Ê ‘ )messageBufferPtr ° d ONLN dU⁄ fiÊ )_ StringPtr ° d ONLN d_⁄/Ê )Q1If messageBufferPtr is not nil, then it points to ° d ONLN dïÁ/Û *
-a Str255 buffer where the foreign file system ° d ONLN d«Û/ˇ * 0can return its own alert message when an illegal ° d ONLN d¸ˇ/ ë * character is detected. ° d ONLN d l x ( lÆ ° d ONLN d ¡ ) charByteType ° d ONLN d" fi ˆ )_short ° d ONLN d(/˚ )Q,Contains the identity of theChar as a 1-byte ° d ONLN dY /( *
4character or as the first or second byte of a 2-byte ° d ONLN dí(/4∑ * character. The values can be: ° d ONLN d¥48@r + smFirstByte ° d ONLN d¿4Ä@ )H First byte of a 2-byte character ° d ONLN dÂ@8Lz (I8 smSingleByte ° d ONLN dÚ@ÄLÀ )H1-byte character ° d ONLN dL8Xp (U8
smLastByte ° d ONLN dLÄX )H Second byte of 2-byte character ° d ONLN d5X/d (a/-smFirstByte, smSingleByte, and smLastByte are ° d ONLN dgd/pã * defined in Script.h. ° d ONLN d|Ä `å (â `YForeign file systems must be able to determine if a volume name is valid. The volume name ° d ONLN d÷å `ò µ * must be validated: ° d ONLN dȧ l∞ p + • ° d ONLN dΧ y∞ )
Yas characters are entered into the name field in the disk initialization dialog box. This ° d ONLN dE∞ yº
* Wgives the foreign file system an opportunity to examine the syntax of the name as it is ° d ONLN dùº y» À * being assembled. +_-9Using the Disk Initialization Package Component Interface (Ú 4- )
9 ˇË d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d U T a X + +• ° d ONLN d U a a )
Twhen the volume format selected in the Format pop-up menu in the disk initialization ° d ONLN d W a a mÔ * Tdialog box changes. This gives the foreign file system an opportunity to examine the ° d ONLN d ¨ m a yj * 9syntax of the name already entered in the the name field. ° d ONLN d Ê Ö T ë X ( é T• ° d ONLN d Ë Ö a ë˚ )
° d ONLN djø HÀÒ *XThe diCIGetVolTypeInfo function selector allows a foreign file system that supports more ° d ONLN d√À H◊Í * Vthan one volume type to provide a list of those volume types. The paramBlock parameter ° d ONLN d◊ H„ * )points to a DICIGetVolTypeInfoRec record. ° d ONLN dD˜ T · + DICIGetVolTypeInfoRec , Symbol ° d ONLN dZ T ` *Æ ° d ONLN d\ g ä )volSize ° d ONLN dd Δ )_
unsigned long ° d ONLN drŸ )Q*Contains the disk capacity in disk sectors ° d ONLN d° „ *
+(sectors may not be the same size as blocks ° d ONLN d— ,ß * used by a foreign file system). ° d ONLN dÒ, T= ` (9 TÆ ° d ONLN dÛ0 g< ó )
sectorSize ° d ONLN d˛0 Δ< )_unsigned short ° d ONLN d
0<” )Q'Contains the number of bytes per sector ° d ONLN d9=I„ *
+(sectors may not be the same size as blocks ° d ONLN diIUß * used by a foreign file system). ° d ONLN dâU Tf ` (b T¨ ° d ONLN dãY ge ™ ) numVolTypes ° d ONLN dóY Δe fi )_short ° d ONLN dùYeÌ )Q-The foreign file system returns the number of ° d ONLN dœfr« *
'volume types it supports in this field. ° d ONLN d˜r TÉ ` ( T¨ ° d ONLN d˘v gÇ ¿ )volTypesBuffer[4] ° d ONLN d v ΔÇ ‡ )_Str32 ° d ONLN dvÇÁ )Q,The foreign file system returns the names of ° d ONLN dBÉèÒ *
0volume types it supports in these string fields. (Ú H4- )
10 )&9Using the Disk Initialization Package Component Interface ˇL d ˇ ˇˇˇˇ d
d , Times
. ( 383The Disk Initialization Package Component Interface ° d ONLN d U ` a ( ^ `VSome file systems support more than one volume type, for example Macintosh File System ° d ONLN d W a ` m
° d ONLN dU ` *XThe diCIGetFormatString function selector allows a foreign file system to supply strings ° d ONLN dÆ `+ * ]used to build the Format pop-up menu and help balloons used in the disk initialization dialog ° d ONLN d + `7Œ * Hbox. The paramBlock parameter points to a DICIGetFormatStringRec record. ° d ONLN dUK lW ¸ + DICIGetFormatStringRec , Symbol ° d ONLN dlW lh x *Æ ° d ONLN dn[ g ¢ )volSize ° d ONLN dv[ fig! )_
unsigned long ° d ONLN dÑ[/gÒ )Q*Contains the disk capacity in disk sectors ° d ONLN d≥h/t˚ *
+(sectors may not be the same size as blocks ° d ONLN d„t/Äø * used by a foreign file system). ° d ONLN d Ä lë x (ç lÆ ° d ONLN d Ñ ê Ø )
sectorSize ° d ONLN d Ñ fiê$ )_unsigned short ° d ONLN d Ñ/êÎ )Q'Contains the number of bytes per sector ° d ONLN d Kë/ù˚ *
. +H3 Guide to the File System Manager , Symbol ° d ONLN d U T f ` + /Æ ° d ONLN d Y g e ¥ )volTypeSelector ° d ONLN d Y Δ e fi )_short ° d ONLN d Y eˆ )Q0Contains the volume type selector if the foreign ° d ONLN d M f r‚ *
)file system supports more than one volume ° d ONLN d { r ~÷ * 'type (diCIHasMultiVolTypesBit is set in ° d ONLN d ß ~ ä· * )the compInterfMask field of the DICIRec). ° d ONLN d — ä T õ ` ( ó TÆ ° d ONLN d ” é g ö ö )
stringKind ° d ONLN d fi é Δ ö fi )_short ° d ONLN d ‰ é öfi )Q*Contains the kind of string requested. The ° d ONLN d õ ßE *
kinds are: ° d ONLN d" ß ≥è + diCIAlternateFormatStr ° d ONLN d9 ßô ≥‚ )yget the alternate ° d ONLN dQ ≥ô ø÷ *
format string ° d ONLN dc ø Àë ( » diCISizePresentationStr ° d ONLN d{ øô ÀÕ )y get the size ° d ONLN dé Àô ◊ * presentation string ° d ONLN d¢ ◊ T Ë ` ( ‰ T¨ ° d ONLN d§ € g Á ° ) stringBuffer ° d ONLN d± € Δ Á Ê )_Str255 ° d ONLN d∏ € Á◊ )Q*The foreign file system returns the string ° d ONLN dÁ Ë ÙÄ *
requested in this field. ° d ONLN d HÁ (
HVA foreign file system can supply strings used to build the Format pop-up menu and help ° d ONLN dW H ˆ * _balloons used in the disk initialization dialog box. If the foreign file system doesn’t provide ° d ONLN d∑ H(Û * [the string, it can return diCIUnknownDICallErr and Disk Initialization Package will use its ° d ONLN d( H4 è * default strings. ° d ONLN d$@ HL¸ *_If stringKind is diCIAlternateFormatStr, the foreign file system can provide a string that will ° d ONLN dÑL HX˚ * Ybe used augment the help balloon displayed for a volume type in the Format pop-up menu in ° d ONLN dfiX Hd * athe disk initialization dialog box. For example, without the alternate format string, the balloon ° d ONLN d@d Hp“ * Ttext for an Macintosh 800K disk reads “To erase the selected disk and change it to a ° d ONLN dïp H|¯ * \Macintosh 800K disk, choose this item, then click Erase.” With the alternate format string “ ° d ONLN dÚ| HàÏ * V(also known as a double-sided Macintosh disk)”, the balloon text for an Macintosh 800K ° d ONLN dIà Hî * \disk reads “To erase the selected disk and change it to a Macintosh 800K disk (also known as ° d ONLN d¶î H†â * Da double-sided Macintosh disk), choose this item, then click Erase.” ° d ONLN dΨ H∏È *[If stringKind is diCISizePresentationStr, the foreign file system can provide a string that ° d ONLN dG∏ Hƒ˝ * ]replaces the volume type in the Format pop-up menu in the disk initialization dialog box. For ° d ONLN d•ƒ H–˚ * \example, by supplying the size presentation string, the volume type string in the Format pop ° d ONLN dƒ˚–ˇ (Õ˚- ° d ONLN d– H‹’ (Ÿ HLup menu could be changed from “Macintosh 720K” to “Macintosh HFS Interchange ° d ONLN dO‹ HË s * Format”. ° d ONLN dX¸ T ê + Result codes ° d ONLN de g Ç + noErr ° d ONLN dk ˙ )ì0 ° d ONLN dmD )!No error ° d ONLN dv g ⁄ ( gdiCIUnknownDICallErr ° d ONLN dã Ù )ç25 ° d ONLN dé „ )'+The requested string isn’t provided by this ° d ONLN dΩ ,s * foreign file system , Helvetica
° d ONLN d—H HW (S HdiCIGetExtFormatParams
° d ONLN dËb Hn *UThe diCIGetExtFormatParams function selector allows a foreign file system a chance to ° d ONLN d>n HzÛ * [query the user (or another part of the system) for additional formatting information beyond ° d ONLN döz HÜ˝ * `that supplied by the disk initialization dialog box provided by the Disk Initialization Package. ° d ONLN d˚Ü Hí¨ * EThe paramBlock parameter points to a DICIGetExtendedFormatRec record. ° d ONLN d A¶ T≤ ı + DICIGetExtendedFormatRec ° d ONLN d Z≤ T√ ` *Æ ° d ONLN d \∂ g¬ ¶ ) driveNumber ° d ONLN d h∂ Δ¬ fi )_short ° d ONLN d n∂¬Ì )Q-Contains the drive number of the device to be ° d ONLN d †√œH *
initialized. (Ú H4- )
12 )&9Using the Disk Initialization Package Component Interface ˇ® d ˇ ˇˇˇˇ d
d , Times
. ( 383The Disk Initialization Package Component Interface , Symbol ° d ONLN d U l f x ( b lÆ ° d ONLN d Y e à )volTypeSelector ° d ONLN d Y fi e ˆ )_short ° d ONLN d Y/ e )Q0Contains the volume type selector if the foreign ° d ONLN d M f/ r˙ *
)file system supports more than one volume ° d ONLN d { r/ ~Ó * 'type (diCIHasMultiVolTypesBit is set in ° d ONLN d ß ~/ ä˘ * )the compInterfMask field of the DICIRec). ° d ONLN d — ä l õ x ( ó lÆ ° d ONLN d ” é ö ¢ )volSize ° d ONLN d € é fi ö! )_
unsigned long ° d ONLN d È é/ öÒ )Q*Contains the disk capacity in disk sectors ° d ONLN d õ/ ß˚ *
+(sectors may not be the same size as blocks ° d ONLN dH ß/ ≥ø * used by a foreign file system). ° d ONLN dh ≥ l ƒ x ( ¿ lÆ ° d ONLN dj ∑ √ Ø )
sectorSize ° d ONLN du ∑ fi √$ )_unsigned short ° d ONLN dÑ ∑/ √Î )Q'Contains the number of bytes per sector ° d ONLN d∞ ƒ/ –˚ *
+(sectors may not be the same size as blocks ° d ONLN d‡ –/ ‹ø * used by a foreign file system). ° d ONLN d ‹ l Ì x ( È lÆ ° d ONLN d ‡ Ï ÷ )fileSystemSpecPtr ° d ONLN d ‡ fi Ï )_ FSSpecPtr ° d ONLN d ‡/ Ïı )Q+Contains a pointer to foreign file system’s ° d ONLN dN Ì/ ˘X *
FSSpec. ° d ONLN dV ˘ l
x ( l¨ ° d ONLN dX ˝ À )extendedInfoPtr ° d ONLN dh ˝ fi Ï )_Ptr ° d ONLN dl ˝/ )Q0The foreign file system returns a pointer to the ° d ONLN d°
/ *
.extended formatting information in this field. ° d ONLN d–& `2Ù (/ `UA foreign file system may need more information from the user (or another part of the ° d ONLN d&2 `>´ * Gsystem) than can be provided by the disk initialization dialog box. The ° d ONLN dn> `J * [diCIGetExtFormatParams function selector allows a foreign file system a chance to query the ° d ONLN d J `V * auser for extended formatting information after the user selects the Erase or Initialize button in ° d ONLN d,V `b * ]the disk initialization dialog box. The diCIGetExtFormatParams function selector is called if ° d ONLN däb `nÚ * Tthe diCIHasExtFormatParamsBit is set in the compInterfMask field of the foreign file ° d ONLN dfln `z ª * system’s DICIRec. ° d ONLN dÒÜ `í *VWhen called with the diCIGetExtFormatParams function selector, the foreign file system ° d ONLN dHí `û * [should allocate memory (if it hasn’t done so when called with the diLoad function selector) ° d ONLN d§û `™
* Zfor the extended formatting information structure, open its resource fork using the FSSpec ° d ONLN dˇ™ `∂ * Zpassed in the fileSystemSpecPtr field, display one or more dialogs to collect the extended ° d ONLN dZ∂ `¬˛ * Zinformation, close its resource fork, and then return a pointer to the extended formatting ° d ONLN dµ¬ `Œ * ^information in the extendedInfoPtr field. When called with the diUnload function selector, the ° d ONLN dŒ `⁄Ë * Tforeign file system should dispose of its extended formatting information structure. ° d ONLN diÊ `Ú¸ *UAny dialogs displayed should contain both a “Continue” and a “Cancel” button with the ° d ONLN døÚ `˛ * ^“Continue” button as the default selection. If the “Continue” button is selected, noErr should ° d ONLN d ˛ `
˛ * Ybe returned as the result along with the extended formatting information. If the “Cancel” ° d ONLN dx
`≠ * Gbutton is selected, diCIUserCancelErr should be returned as the result. ° d ONLN d¿" `. *ZThe extended formatting information data structure used by your foreign file system should ° d ONLN d . `: * [be documented so that application programs can pass the information programmatically in the ° d ONLN d w: `F ¥ * DIXZero request. ° d ONLN d àZ lf ® + Result codes ° d ONLN d ïf r ö + noErr ° d ONLN d õfr )ì0 ° d ONLN d ùf3r\ )!No error ° d ONLN d ¶r ~ ⁄ ({ diCIUserCancelErr ° d ONLN d ∏r~ )ì1 ° d ONLN d ∫r3~ )!,The “Cancel” button was selected by the user (Ú ÿ9Using the Disk Initialization Package Component Interface (Ú4- )
13 ˇ d ˇ ˇˇˇˇ d
d , Helvetica
. ° d ONLN d V ` h € +`d APPENDIX A: ° d ONLN d V hπ )êTHE EXTENDED DISK Q ^ Q ° d ONLN d l ~Â *INITIALIZATION PACKAGE ~ ^ ~ , Times
(ÚA- ) 1 ˇ
ƒ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager , Helvetica
° d ONLN d U H d ˆ *-ABOUT THIS APPENDIX N F N g F g
° d ONLN d ~ H ä *'QThis appendix documents three Disk Initialization Package functions not found in ° d ONLN d e ~ äÁ ( á Inside ° d ONLN d l ä H ñ ñ ( ì HMacintosh: Files ° d ONLN d | ä ñ ñ ö )N.
° d ONLN d ~ ª H ^ ( Δ H APPLICATION PROGRAM INTERFACE ¥ F ¥ Õ F Õ
° d ONLN d ú ‰ H Ù *']The existing application program interface to the Disk Initialization Package as described in ° d ONLN d ˙ H ¸ ∂ * Inside Macintosh: Files ° d ONLN d ∂ ¸Á )nB will continue to be supported by the enhanced Disk Initialization ° d ONLN dT ¸ H' ( H0Package. Applications which wish to initialize ° d ONLN dÑ ¸'< )flonly ° d ONLN dà ¸<˜ )' Macintosh disks will continue to work ° d ONLN d∞ HÓ ( HYand will require no changes. However, if an application wants to initialize non-Macintosh ° d ONLN d
H  * Sdisks, it must use the new extended DIXFormat and DIXZero calls as described below. ° d ONLN d^, H8˝ *\Extended programmatic interfaces to media formatting and volume initialization functions are ° d ONLN dª8 HD˜ * ]required such that applications may specify additional information for the overall formatting ° d ONLN dD HPÚ * [operation. This information corresponds to the new items in the user interface described in ° d ONLN duP H\Î * Ythe previous section: file system type and disk size. The extended programmatic interface ° d ONLN dœ\ Hhı * Xadds three new functions to the Disk Initialization Package called DIXFormat and DIXZero ° d ONLN d(h HtL * 3(for extended DIFormat and DIZero), and DIReformat. ° d ONLN d\Ä Tå ê +
Warning: ° d ONLN dfÄ êå‡ )<HApplications should insure that the extended Disk Initialization Package ° d ONLN dØå Tò‚ (ï TPfunctions are present before making the DIXFormat, DIXZero, or DIReformat calls. ° d ONLN d ò T§” * RThis is done by calling Gestalt with the gestaltFSAttr selector. The extended Disk ° d ONLN dS§ T∞› * YInitialization Package functions is available if the Gestalt function returns a result of ° d ONLN d≠∞ Tº‡ * UnoErr and the gestaltHasExtendedDiskInitbit (bit 6) is set in the response parameter. ° d ONLN dº T»– * RDue to the nature of older versions of the Disk Initialization Package, making the ° d ONLN dV» T‘´ * Gextended requests when they are not available may cause a system crash. ° d ONLN dûÊ HÚÎ (Ô H\Listing 5-1 illustrates how you use Gestalt to determine if the extended Disk Initialization ° d ONLN d˚Ú H˛ fl * Package functions are available. ° d ONLN d
u π +- Listing 5-1. ° d ONLN d(
π’ )D< Testing for extended Disk Initialization Package functions ,
Courier
° d ONLN de H+ r (( HBoolean ° d ONLN dm ~+& )6 HasExtendedDIFunctions(void) ° d ONLN dä+ H7 N (4 H{ ° d ONLN dç7 ZC Æ + long response; ° d ONLN düO Z[t */if (Gestalt(gestaltFSAttr, &response) == noErr) ° d ONLN d—[ lg‡ + >return ((response & (1L << gestaltHasExtendedDiskInit)) != 0); ° d ONLN dg Zs r (p Zelse ° d ONLN ds l Δ + return (false); ° d ONLN d( Hã N (à H}
*jA- ) 2 )$ Application Program Interface ˇò d ˇ ˇˇˇˇ d
d , Times
. ( 3Z(The Extended Disk Initialization Package , Helvetica
° d ONLN d U ` d Æ ( ` ` DIXFormat d ^ d§
° d ONLN d
q ` } *VThe DIXFormat function performs the same function as the DIFormat function except that ° d ONLN d a } ` â „ * drive size may be specified. ,
Courier
° d ONLN d ~ ñ ` ¢û *5pascal OSErr DIXFormat(short drvNum, Boolean fmtFlag, ° d ONLN d ª ¢ ˜ Æ +ó .unsigned long fmtArg, unsigned long *actSize);
° d ONLN d Í π ` ≈ à ( ¬ `drvNum ° d ONLN d Ò π Ã ≈∏ )l2Contains the driver number of the drive to format. ° d ONLN d$ Õ ` Ÿ Ö ( ÷ `fmtFlag ° d ONLN d, Õ Ã Ÿ
)lBContains a boolean value which specifies the meaning of the fmtArg ° d ONLN do Ÿ à  ˘ * paramter. ° d ONLN dy Ì ` ˘ Ç ( ˆ `fmtArg ° d ONLN dÄ Ì Ã ˘ )lIIf fmtFlag is true, fmtArg specifies the actual value to be passed to the ° d ONLN d ˘ Ã˘ * @disk driver in the csParam field of the parameter block when the ° d ONLN d à * G“format” _Control call is made to initialize the disk media. (The value ° d ONLN dS à * His an index into the size list. For an explanation of appropriate values ° d ONLN dú Ã)
* Afor this parameter, see the Technical Note “What Your Sony Drives ° d ONLN dfi) Ã5 *
For You”.) ° d ONLN dÈ5 ÃA * FIf fmtFlag is false, fmtArg specifies the desired size of the media in ° d ONLN d0A ÃM * Dnumber of 512-byte blocks. The disk driver is called to get possible ° d ONLN duM ÃY * Esizes and the values in an to attempt to match the requested size. If ° d ONLN dªY Ãeì * -more than one size list entry exists for the ° d ONLN dËYìe¿ )« same size ° d ONLN dÒY¿e )-, the first entry in ° d ONLN de Ãq (n ÃFthe list returned by the driver that best matches the fmtArg parameter ° d ONLN dMq Ã}Ì * ?will be used. For more information about the size list, see the ° d ONLN dç} Ãâ
* @Technical Note “What Your Sony Drives For You”. If the specified ° d ONLN dŒâ Ãï * Msize is larger than the largest size in the size list returned by the driver, ° d ONLN d ï ð * Kthen the largest size will be used and that size is returned in actSize. If ° d ONLN dh° Ã≠ı * Ethe specified size is smaller than the smallest size in the size list ° d ONLN dÆ≠ Ãπ * Ireturned by the driver, then the smallest size will be used and that size ° d ONLN d¯π Ã≈ * Dis returned in actSize. For a specified value that is in between and ° d ONLN d=≈ ע * Awithout an exact match, the value closest to and smaller than the ° d ONLN d— Û6 * requested size is used. ° d ONLN dó `Ò Å (Ó `actSize ° d ONLN dü ÃÒ )l<Contains a pointer to an unsigned long. Upon completion of a ° d ONLN d‹Ò Ã˝ * Dsuccessful formatting operation, DIXFormat places the actual size of ° d ONLN d!˝ à ˆ * ?the formatted media in number of 512-byte blocks into the field ° d ONLN da ÃU * referred to by this parameter. ° d ONLN dÄ' `3 (0 `\The formatting of file systems requiring specific media formats should be done by specifying ° d ONLN d›3 `? * [those media formats explicitly and not by counting on disk size alone. Foreign file systems ° d ONLN d9? `K * _with specific media requirements should use the driver specific information in the size list or ° d ONLN dôK `W * [should make appropriate driver _Status calls for additional information when called upon to ° d ONLN dıW `c À * “evaluate the size list”. ° d ONLN d o `{ı *NAs in DIFormat, DIXFormat does not unmount the volume. You have to unmount the ° d ONLN d ^{ `á * Xvolume before issuing this call if necessary. If the volume has not been unmounted, then ° d ONLN d ∑á `ì( * (DIXFormat will return volOnLinErr error. +˛b Application Program Interface )´A- ) 3 ˇ~ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d i T u ê + ? Result codes ° d ONLN d
u g Å Ç + noErr ° d ONLN d u ˆ Å ¸ )è0 ° d ONLN d u ÅD )%No error ° d ONLN d Å g ç ¶ ( ä g volOnLinErr ° d ONLN d + Å Ï ç ¸ )Ö-55 ° d ONLN d / Å çk )/Volume is online ° d ONLN d @ ç g ô ô ( ñ g
lastDskErr ° d ONLN d K ç Ï ô ¸ )Ö-64 ° d ONLN d O ç ô‹ )/*Last of the range of low-level disk errors ° d ONLN d z ô g • s ( ¢ g... ° d ONLN d ~ • g ± ú * firstDskErr ° d ONLN d ä • Ï ± ¸ )Ö-84 ° d ONLN d é • ±fi )/+First of the range of low-level disk errors , Helvetica
° d ONLN d ∫ ” H ‚ Ñ ( fi HDIXZero ‚ F ‚å
° d ONLN d ¬ Ô H ˚˚ *[The DIXZero function performs the same function as the DIZero function except that the file ° d ONLN d ˚ H * Zsystem, format result, volume type, volume size and extended formatting information may be ° d ONLN dy H v *
specified. ,
Courier
° d ONLN dÑ H,¯ *Hpascal OSErr DIXZero(short drvNum, ConstStr255Param volName, short fsid, ° d ONLN d‘, fl8’ +ó )short mediaStatus, short volTypeSelector, ° d ONLN d8 flDÛ * .unsigned long volSize, void *extendedInfoPtr);
° d ONLN d4O H[ p (X HdrvNum ° d ONLN d;O ¥[® )l6Contains the driver number of the drive to initialize. ° d ONLN drc Ho s (l HvolName ° d ONLN dzc ¥oÙ )lEContains a pointer to a Pascal string which specifies the name of the ° d ONLN d¿o ¥{ € * volume. ° d ONLN d»É Hè Z (å Hfsid ° d ONLN dÕÉ ¥è˜ )lDContains the ID of the file system whose format should be written to ° d ONLN dè ¥õÏ * Bthe disk. The file system ID can be obtained using the File System ° d ONLN dUõ ¥ßA * Manager GetFSInfo function. ° d ONLN dqØ Hª Å (∏ H mediaStatus ° d ONLN d}Ø ¥ª¸ )lJContains a flag to indicate the status of the disk media. Its value is the ° d ONLN d»ª ¥«˛ * Fresult code returned from the DIVerify function. If mediaStatus is non ° d ONLN dª˛« (ƒ˛- ° d ONLN d« ¥”˚ (– ¥Gzero, then the disk contains bad sectors and needs to be spared. If the ° d ONLN dW” ¥flÕ * <file system specified doesn’t support bad block sparing (the ° d ONLN dîfl ¥Î * @diCIDoesSparingBit in the compInterfMask field of the DICIRec is ° d ONLN d’Î ¥˜˘ * Jclear), the Disk Initialization Package will just return this value as the ° d ONLN d ˜ ¥˝ * Hfunction result. If the file system supports bad block sparing, then the ° d ONLN di ¥˘ * JDisk Initialization Package will gather the defect list and pass it to the ° d ONLN d¥ ¥ Î * file system. ° d ONLN d¡# H/ ï (, HvolTypeSelector ° d ONLN d—# ¥/ı )lEContains the volume type selector if the foreign file system supports ° d ONLN d/ ¥; * @more than one volume type (diCIHasMultiVolTypesBit is set in the ° d ONLN dX; ¥G¨ * 3compInterfMask field of the file system’s DICIRec). ° d ONLN dåO H[ k (X HvolSize ° d ONLN dîO ¥[¯ )lFContains the size in 512-byte blocks of the file system that should be ° d ONLN d€[ ¥g˜ * Fwritten to the drive specified by drvNum. This is the size returned in ° d ONLN d"g ¥s˘ * Ethe actSize field by DIXFormat - the amount of space usable by a file ° d ONLN dhs ¥€ * Bsystem on the specified drive as it is currently formatted. If the ° d ONLN d´ ¥ã◊ * ?specified size doesn't match with the current disk format size, ° d ONLN dÎã ¥óë * +DIXZero will return diCIVolSizeMismatchErr. ° d ONLN dü H´ t (® HfsParams ° d ONLN d ü ¥´Ï )lCContains a pointer to the foreign file system’s extended formatting ° d ONLN dd´ ¥∑ø * 7information (if diCIHasExtFormatParamsBit is set in the ° d ONLN dú∑ ¥√ç * -compInterfMask field of the DICIRec), or nil. (Ú HA- ) 4 )$ Application Program Interface ˇ
~ d ˇ ˇˇˇˇ d
d , Times
. ( 3Z(The Extended Disk Initialization Package ° d ONLN d U ` aı ( ^ `QAs in DIZero, DIXZero does not unmount the volume but it will, however, mount the ° d ONLN d R a ` m
* Yvolume if the operation is successful. You have to unmount the volume before issuing this ° d ONLN d ¨ m ` yÒ * Tcall if necessary. If the volume is mounted when DIZero or DIXZero is called, then a ° d ONLN d y ` Ö * #volOnLinErr error will be returned. ° d ONLN d% ô l • ® + Result codes ° d ONLN d2 • ± ö + noErr ° d ONLN d8 • ± )è0 ° d ONLN d: •3 ±\ )%No error ° d ONLN dC ± Ω ó ( ∫ ioErr ° d ONLN dI ± Ω )Ö-36 ° d ONLN dM ±3 Ω\ )/ I/O error ° d ONLN dW Ω … ´ ( Δ paramErr ° d ONLN d` Ω … )Ö-50 ° d ONLN dd Ω3 …¿ )/ Drive number specified is bad ° d ONLN dÇ … ’ æ ( “ volOnLinErr ° d ONLN dè … ’ )Ö-55 ° d ONLN dì …3 ’® )/Volume is already online ° d ONLN d¨ ’ · ´ ( fi nsDrvErr ° d ONLN dµ ’ · )Ö-56 ° d ONLN dπ ’3 ·v )/
No such drive ° d ONLN d« · Ì ± ( Í
lastDskErr ° d ONLN d“ · Ì )Ö-64 ° d ONLN d÷ ·3 ÌÙ )/*Last of the range of low-level disk errors ° d ONLN d Ì ˘ ã ( ˆ ... ° d ONLN d ˘ ¥ * firstDskErr ° d ONLN d ˘ )Ö-84 ° d ONLN d ˘3ˆ )/+First of the range of low-level disk errors ° d ONLN dA ∏ (
memFullErr ° d ONLN dL ˛ )-108 ° d ONLN dQ3ï )5Not enough memory , Helvetica
° d ONLN dc3 `B ≥ (> `
DIReformat B ^B§
° d ONLN dnO `[H *.The DIReformat function reformats disk volume. ,
Courier
° d ONLN dùh `tÜ *1pascal OSErr DIReformat(short drvNum, short fsid, ° d ONLN d÷t ˜Äç +ó ConstStr255Param volName, ° d ONLN dˆÄ ˜åì * ConstStr255Param msgText);
° d ONLN dó `£ à († `drvNum ° d ONLN dó ã∏ )l2Contains the driver number of the drive to format. ° d ONLN dK´ `∑ r (¥ `fsid ° d ONLN dP´ Ã∑ )lDContains the ID of the file system whose format should be written to ° d ONLN dï∑ Ã√ * Bthe disk. The file system ID can be obtained using the File System ° d ONLN dÿ√ ÃœY * Manager GetFSInfo function. ° d ONLN dÙ◊ `„ ã (‡ `volName ° d ONLN d¸◊ Ä )lEContains a pointer to a Pascal string which specifies the name of the ° d ONLN dB„ ÃÔ Û * volume. ° d ONLN dJ˜ ` â ( `msgText ° d ONLN dR˜ à )lEContains a pointer to a Pascal string which specifies the explanatory ° d ONLN dò Ö * ;text to be displayed in the disk initialization dialog box. ° d ONLN d‘! `- (* `[In the past, reformatting disk was accomplished by calling the DIBadMount function with the ° d ONLN d0- `9 * \high word of the evtMessage parameter set to noErr and the explanatory text was set with the ° d ONLN dç9 `E * ZParamText function. The DIReformat function provides the caller the ability to provide the ° d ONLN dËE `Q * \explanatory text, the default file system ID, and the default name for the reformatted disk. ° d ONLN dE] li ã + Note: ° d ONLN dJ] ãik ) . The volume in the drive specified by drvNum ° d ONLN dx]kiê )‡must be ° d ONLN d]êi˚ )% mounted when calling ° d ONLN dïi lu ´ (r l DIReformat . +ÚÄ Application Program Interface )´A- ) 5 ˇJ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ° d ONLN d i T u ê + ? Result codes ° d ONLN d
u g Å Ç + noErr ° d ONLN d u ˆ Å ¸ )è0 ° d ONLN d u ÅD )%No error ° d ONLN d Å g ç ÿ ( ä gdiCINoMessageTextErr ° d ONLN d 3 Å ç ¸ )â28 ° d ONLN d 6 Å çô )+msgText was not provided ° d ONLN d O ç g ô ì ( ñ gparamErr ° d ONLN d X ç Ï ô ¸ )Ö-50 ° d ONLN d \ ç ô® )/ Drive number specified is bad ° d ONLN d z ô g • ì ( ¢ gnsDrvErr ° d ONLN d É ô Ï • ¸ )Ö-56 ° d ONLN d á ô •^ )/
No such drive ° d ONLN d ï • g ± ô ( Æ g
lastDskErr ° d ONLN d † • Ï ± ¸ )Ö-64 ° d ONLN d § • ±‹ )/*Last of the range of low-level disk errors ° d ONLN d œ ± g Ω s ( ∫ g... ° d ONLN d ” Ω g … ú * firstDskErr ° d ONLN d fl Ω Ï … ¸ )Ö-84 ° d ONLN d „ Ω …fi )/+First of the range of low-level disk errors ° d ONLN d … g ’ † ( “ g
memFullErr ° d ONLN d … Ê ’ ¸ )-108 ° d ONLN d … ’} )5Not enough memory (Ú HA- ) 6 )$ Application Program Interface ˇ d ˇ ˇˇˇˇ d
d , Helvetica
. ° d ONLN d V ` h € +`d APPENDIX B: ° d ONLN d V h¸ )êADDITIONAL FILE MANAGER Q ^ Q ° d ONLN d $ l ~U *ROUTINES ~ ^ ~ , Times
(ÚB- ) 1 ˇ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager , Helvetica
° d ONLN d U H d ˆ *-ABOUT THIS APPENDIX N F N g F g
° d ONLN d ~ H äÜ *'BThis appendix documents two File Manager routines that are not in ° d ONLN d W ~Ü äÙ ( áÜInside Macintosh: Files ° d ONLN d o ä H ñ0 ( ì H0but must be documented for foreign file systems.
° d ONLN d † ª H ^ *3 APPLICATION PROGRAM INTERFACE ¥ F ¥ Õ F Õ
° d ONLN d æ ‰ H ˚ *'RThe following two functions, PBHUnmountVol and PBGetXCatInfo are not documented in ° d ONLN d H ¸ ∂ * Inside Macintosh: Files ° d ONLN d( ∂ ¸Ò )n>. Foreign file systems must respond correctly to PBHUnmountVol ° d ONLN dg ¸ H˘ ( HSand may want to support PBGetXCatInfo. Applications may use PBGetXCatInfo, but must ° d ONLN dª H b * never ° d ONLN d¿ b “ ) call PBHUnmountVol. ,
Zapf Dingbats
° d ONLN d’ T, _ (* Ts ° d ONLN d◊! f- ö )Warning: ° d ONLN dfl! ö-Ë )4B PBHUnmountVol is reserved for use only by the Macintosh operating ° d ONLN d"- f9È (6 fJsystem. The operating system uses PBHUnmountVol to unconditionally unmount ° d ONLN dm9 fE« * Ivolumes before system shutdown or restart. Applications should never call ° d ONLN d∑E fQÀ * CPBHUnmountVol because PBHUnmountVol can close files in use by other ° d ONLN d˚Q f]Å * <applications which can cause data loss or media corruption.
° d ONLN d7SÅ\â (ZÅs
° d ONLN d9{ Hä ø (Ü H
PBHUnmountVol ä Fäå
° d ONLN dGó H£â *<The PBHUnmountVol function unconditionally unmounts a volume ,
Courier
° d ONLN dÑ∞ Hºt *2pascal OSErr PBHUnmountVol(ParmBlkPtr paramBlock);
° d ONLN d∑« H” Å *
paramBlock ° d ONLN d¬« ¥”q )l&Contains a pointer to a ParamBlockRec. ° d ONLN dÈÌ T˘ ≠ (ˆ T
ParamBlockRec , Symbol ° d ONLN d˜˘ T
` *¨ ° d ONLN d˘˝ g é )ioResult ° d ONLN d˝ Δ ‰ )_OSErr ° d ONLN d˝ ´ )Q The result code of the function. ° d ONLN d)
T ` ( TÆ ° d ONLN d+ g ö ) ioNamePtr ° d ONLN d5 Δ Ò )_ StringPtr ° d ONLN d?ã )QA pointer to a pathname. ° d ONLN dX T, ` (( TÆ ° d ONLN dZ g+ ° ) ioVRefNum ° d ONLN dd Δ+ fi )_short ° d ONLN dj +˛ )Q.A volume reference number, a working directory ° d ONLN dù,8Î *
,reference number, drive number, or 0 for the ° d ONLN dŒ8Da * default volume. ° d ONLN dfiT H` (] HXThe PBHUnmountVol function unconditionally unmounts the specified volume. All user files ° d ONLN d7` Hlá * Bon the volume will be closed by the file system owning the volume. ° d ONLN dzx HÑy *9The PBHUnmountVol function always executes synchronously.
(Ú HB- ) 2 )$ Application Program Interface ˇÑ d ˇ ˇˇˇˇ d
d , Times
. ( 3w!Additional File Manager Functions ° d ONLN d U ` a9 ( ^ ` ASSEMBLY-LANGUAGE INFORMATION ° d ONLN d m ` y: *(The trap word for PBHUnmountVol is A20E. ° d ONLN d G ç l ô ® + Result codes ° d ONLN d T ô • ö + noErr ° d ONLN d Z ô • )è0 ° d ONLN d \ ô3 •\ )%No error ° d ONLN d e • ± ü ( Æ nsvErr ° d ONLN d l • ± )É–35 ° d ONLN d p •3 ±÷ )1 No such volume reference number ° d ONLN d ê ± Ω ó ( ∫ ioErr ° d ONLN d ñ ± Ω )É–36 ° d ONLN d ö ±3 Ω\ )1 I/O error ° d ONLN d § Ω … ± ( Δ bdNamErr ° d ONLN d ≠ Ω … )É–37 ° d ONLN d ± Ω3 …à )1Bad volume name ° d ONLN d ¡ … ’ ´ ( “ paramErr ° d ONLN d … ’ )É–50 ° d ONLN d Œ …3 ’ã )1No default volume ° d ONLN d ‡ ’ · ´ ( fi nsDrvErr ° d ONLN d È ’ · )É–56 ° d ONLN d Ì ’3 ·v )1
No such drive ° d ONLN d ˚ · Ì ™ ( Í extFSErr ° d ONLN d · Ì )É–58 ° d ONLN d ·3 Ì÷ )1!No file system claimed the volume , Helvetica
° d ONLN d* ` Õ ( `
PBGetXCatInfo ^ §
° d ONLN d8+ `7 *UYou can use the PBGetXCatInfo function to get the short name (MS-DOS format name) and ° d ONLN dé7 `C6 * -ProDOS information for files and directories. ,
Courier
° d ONLN dºP `\™ *7pascal OSErr PBGetXCatInfoSync(XCInfoPBPtr paramBlock); ° d ONLN dÙ\ `h∞ * 8pascal OSErr PBGetXCatInfoAsync(XCInfoPBPtr paramBlock);
completion routine. ° d ONLN d≈¬ l” x (œ l¨ ° d ONLN d«Δ “ ¶ )ioResult ° d ONLN d–Δ fi“ ¸ )_OSErr ° d ONLN d÷Δ/“ )Q.PBGetXCatInfo places its result code into this ° d ONLN d ”/flH *
field. ° d ONLN dfl l x (Ï lÆ ° d ONLN d„ Ô ≤ ) ioNamePtr ° d ONLN d „ fiÔ )_ StringPtr ° d ONLN d&„/Ô )Q2Contains a pointer to the object name, or nil when ° d ONLN d]/¸ *
0ioDirID specifies a directory that’s the object. ° d ONLN dé¸ l
x ( lÆ ° d ONLN dê π ) ioVRefNum ° d ONLN dö fi ˆ )_short ° d ONLN d† / … )Q Contains a volume specification. ° d ONLN d¡
l x ( lÆ ° d ONLN d√ Ã )ioShortNamePtr ° d ONLN d“ fi ¸ )_OSErr ° d ONLN dÿ/ ¯ )Q,Contains a pointer to a Pascal string buffer ° d ONLN d /* *
((minimum 13 bytes). PBGetXCatInfo places ° d ONLN d6*/6 * 1the short name into the field referred to by this ° d ONLN dl6/BÙ * (parameter. ioShortNamePtr cannot be nil. ° d ONLN dïB lS x (O l¨ ° d ONLN dóF R Ø )ioPDType ° d ONLN d†F fiR ˆ )_short ° d ONLN d¶F/R )Q.PBGetXCatInfo places the ProDOS file type into ° d ONLN dŸS/_\ *
this field. ° d ONLN dÂ_ lp x (l l¨ ° d ONLN dÁc o √ ) ioPDAuxType ° d ONLN dÛc fio Û )_long ° d ONLN d¯c/o )Q)PBGetXCatInfo places the ProDOS auxiliary ° d ONLN d&p/|à *
. +H3 Guide to the File System Manager ° d ONLN d U H aˆ *+]The following data structure and inline glue code is needed for applications that wish to use ° d ONLN d ^ a H m ô * PBGetXCatInfo. ,
Courier
° d ONLN d m Ç T é Ã + !struct XCInfoPBRec { ° d ONLN d Ç é r ö ¢ + QElemPtr ° d ONLN d ã é ÿ ö ¸ )fqLink; ° d ONLN d í ö r ¶ ê ( £ rshort ° d ONLN d ò ö ÿ ¶ ¸ )fqType; ° d ONLN d ü ¶ r ≤ ê ( Ø rshort ° d ONLN d • ¶ ÿ ≤ )fioTrap; ° d ONLN d ≠ ≤ r æ Ñ ( ª rPtr ° d ONLN d ± ≤ ÿ æ )f
ioCmdAddr; ° d ONLN d º æ r ú ( « rProcPtr ° d ONLN d ƒ æ ÿ & )f
ioCompletion; ° d ONLN d “ æD Ï )l /* A pointer to a completion ° d ONLN d Ù V ÷í +
routine */ ° d ONLN d ˇ ÷ r ‚ ê ( fl rOSErr ° d ONLN d ÷ ÿ ‚& )f
ioResult; ° d ONLN d ÷D ‚⁄ )l/* The result code of the ° d ONLN d2 ‚V Óò + function */ ° d ONLN d> Ó r ˙ ® ( ˜ r StringPtr ° d ONLN dH Ó ÿ ˙ )f
ioNamePtr; ° d ONLN dS ÓD ˙Ï )l /* Pointer to object name or ° d ONLN du ˙Vz + nil */ ° d ONLN d| r ê ( rshort ° d ONLN dÇ ÿ )f
ioVRefNum; ° d ONLN dçDÏ )l /* A volume specification */ ° d ONLN d™ r ä ( rlong ° d ONLN dØ ÿ )ffiller1; ° d ONLN d∏ r* ® (' r StringPtr ° d ONLN d¬ ÿ*2 )fioShortNamePtr; ° d ONLN d“ D*¯ )l /* A pointer to the short name ° d ONLN dˆ*V6˛ + string buffer - required! */ ° d ONLN d6 rB ê (? rshort ° d ONLN d6 ÿB )ffiller2; ° d ONLN d"B rN ê (K rshort ° d ONLN d(B ÿN )f ioPDType; ° d ONLN d2BDN‡ )l/* The ProDOS file type */ ° d ONLN dMN rZ ä (W rlong ° d ONLN dRN ÿZ )f ioPDAuxType; ° d ONLN d_NDZ⁄ )l/* The ProDOS aux type */ ° d ONLN dyZ rf ä (c rlong ° d ONLN d~Z ÿf )f
filler[2]; ° d ONLN dâf rr ä (o rlong ° d ONLN déf ÿr )fioDirID; ° d ONLN dófDrº )l/* A directory ID */ ° d ONLN d¨r r~ ~ ({ r}; ° d ONLN dØ~ rä\ * 'typedef struct XCInfoPBRec XCInfoPBRec; ° d ONLN d◊ä rñ8 * !typedef XCInfoPBRec *XCInfoPBPtr; ° d ONLN d˘û H™\ (ß H.#pragma parameter __D0 PBGetXCatInfoSync(__A0) ° d ONLN d(™ H∂å * 6pascal OSErr PBGetXCatInfoSync(XCInfoPBPtr paramBlock) ° d ONLN dd∂ ¢¬ +Z = {0x703A,0xA260}; ° d ONLN dw¬ HŒb (À H/#pragma parameter __D0 PBGetXCatInfoAsync(__A0) ° d ONLN dߌ H⁄í * 7pascal OSErr PBGetXCatInfoAsync(XCInfoPBPtr paramBlock) ° d ONLN d‰⁄ ¢Ê +Z = {0x703A,0xA660};
. ° d ONLN d V ` h ‹ +`d APPENDIX C: ° d ONLN d V h )êFILE SYSTEM ROUTINE TABLE Q ^ Q h ^ h , Times
(ÚC- ) 1 ˇ$˛ d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager , Helvetica
° d ONLN d U H d ˆ *-ABOUT THIS APPENDIX N F N g F g
° d ONLN d ~ H äÿ *'XThis appendix lists all File Manager routine and the select codes that your foreign file ° d ONLN d m ä H ñ * &system’s HFSCIProc can be called with. ,
Courier
° d ONLN d î ± H º r *&Routine ° d ONLN d ú Ω H » ` * Name ° d ONLN d ° ± æ º ‚ ( π æSelect ° d ONLN d ® Ω æ » ÷ * Code ° d ONLN d ≠ ± Í º ( π ÍRequired ° d ONLN d ∂ ±# ºG )9Volume ° d ONLN d Ω Ω# »_ *
Attributes ° d ONLN d » ±r ºê ( πrNotes " Æ C # " Æ Dt " Æ π " Æ ∫* " Æ Â " Æ Ê7 " Æ " Æ M " Æm Æn Ƹ " Æ˝ # " Ø C " Ø π " Ø Â " Ø " Øm " Ø˝ ° d ONLN d œ H ’ ¥ ( “ HFile Manager Traps " « C " « Dt " « π " « ∫* " «  " « Ê7 " « " « M " «m «n «¸ " «˝ " » C " » π " »  " » " »m " »˝ ° d ONLN d Á ◊ H ‚ \ *
Open ° d ONLN d Ï ◊ æ ‚ ◊ )v$A000 ° d ONLN d Ú ◊ Í ‚ Ô ),• " ‘ C " ‘ Dt " ‘ π " ‘ ∫* " ‘  " ‘ Ê7 " ‘ " ‘ M " ‘m ‘n ‘¸ " ‘˝ " ’ C " ’ π " ’  " ’ " ’m " ’˝ ° d ONLN d ˜ ‰ H Ô a ( Ï HClose ° d ONLN d ˝ ‰ æ Ô ◊ )v$A001 ° d ONLN d ‰ Í Ô Ô ),• " · C " · Dt " · π " · ∫* " ·  " · Ê7 " · " · M " ·m ·n ·¸ " ·˝ " ‚ C " ‚ π " ‚  " ‚ " ‚m " ‚˝ ° d ONLN d Ò H ¸ \ ( ˘ HRead ° d ONLN d
Ò æ ¸ ◊ )v$A002 ° d ONLN d Ò Í ¸ Ô ),• " Ó C " Ó Dt " Ó π " Ó ∫* " Ó Â " Ó Ê7 " Ó " Ó M " Óm Ón Ó¸ " Ó˝ " Ô C " Ô π " Ô Â " Ô " Ôm " Ô˝ ° d ONLN d ˛ H a ( HWrite ° d ONLN d ˛ æ ◊ )v$A003 ° d ONLN d$ ˛ Í Ô ),• " ˚ C " ˚ Dt " ˚ π " ˚ ∫* " ˚  " ˚ Ê7 " ˚ " ˚ M " ˚m ˚n ˚¸ " ˚˝ " ¸ C " ¸ π " ¸  " ¸ " ¸m " ¸˝ ° d ONLN d) H z ( H
GetVolInfo ° d ONLN d7 æ ◊ )v$A007 ° d ONLN d= Í Ô ),• " C " Dt " π " ∫* " Â " Ê7 " " M "m n¸ "˝ " C " π " Â " " m " ˝ ° d ONLN dB H# f ( HCreate ° d ONLN dL æ# ◊ )v$A008 ° d ONLN dR Í# Ô ),• " C " Dt " π " ∫* " Â " Ê7 " " M "m n¸ "˝ " C " π " Â " "m "˝ ° d ONLN dW% H0 f (- HDelete ° d ONLN da% æ0 ◊ )v$A009 ° d ONLN dg% Í0 Ô ),• "" C "" Dt "" π "" ∫* "" Â "" Ê7 "" "" M ""m "n"¸ ""˝ "# C "# π "# Â "# "#m "#˝ ° d ONLN dl2 H= f (: HOpenRF ° d ONLN dv2 æ= ◊ )v$A00A ° d ONLN d|2 Í= Ô ),• "/ C "/ Dt "/ π "/ ∫* "/ Â "/ Ê7 "/ "/ M "/m /n/¸ "/˝ "0 C "0 π "0 Â "0 "0m "0˝ ° d ONLN dÅ? HJ f (G HRename ° d ONLN dã? æJ ◊ )v$A00B ° d ONLN dë? ÍJ Ô ),• "< C "< Dt "< π "< ∫* "< Â "< Ê7 "< "< M "<m <n<¸ "<˝ "= C "= π "= Â "= "=m "=˝ ° d ONLN dñL HW (T H GetFileInfo ° d ONLN d§L æW ◊ )v$A00C ° d ONLN d™L ÍW Ô ),• "I C "I Dt "I π "I ∫* "I Â "I Ê7 "I "I M "Im InI¸ "I˝ "J C "J π "J Â "J "Jm "J˝ ° d ONLN dØY Hd (a H SetFileInfo ° d ONLN dΩY æd ◊ )v$A00D ° d ONLN d√Y Íd Ô ),• "V C "V Dt "V π "V ∫* "V Â "V Ê7 "V "V M "Vm VnV¸ "V˝ "W C "W π "W Â "W "Wm "W˝ ° d ONLN d»f Hq z (n H
UnmountVol ° d ONLN d÷f æq ◊ )v$A00E ° d ONLN d‹f Íq Ô ),• "c C "c Dt "c π "c ∫* "c  "c Ê7 "c "c M "cm cnc¸ "c˝ "d C "d π "d  "d "dm "d˝ ° d ONLN d·s H~ p ({ HMountVol ° d ONLN dÎs æ~ ◊ )v$A00F ° d ONLN dÒs Í~ Ô ),• "p C "p Dt "p π "p ∫* "p  "p Ê7 "p "p M "pm pnp¸ "p˝ "q C "q π "q  "q "qm "q˝ ° d ONLN dˆÄ Hã p (à HAllocate ° d ONLN d Ä æã ◊ )v$A010 ° d ONLN dÄ Íã Ô ),• "} C "} Dt "} π "} ∫* "}  "} Ê7 "} "} M "}m }n}¸ "}˝ "~ C "~ π "~  "~ "~m "~˝ ° d ONLN d ç Hò f (ï HGetEOF ° d ONLN dç æò ◊ )v$A011 ° d ONLN dç Íò Ô ),• "ä C "ä Dt "ä π "ä ∫* "ä  "ä Ê7 "ä "ä M "äm änä¸ "ä˝ "ã C "ã π "ã  "ã "ãm "ã˝ ° d ONLN d ö H• f (¢ HSetEOF ° d ONLN d*ö æ• ◊ )v$A012 ° d ONLN d0ö Í• Ô ),• "ó C "ó Dt "ó π "ó ∫* "ó  "ó Ê7 "ó "ó M "óm ónó¸ "ó˝ "ò C "ò π "ò  "ò "òm "ò˝ ° d ONLN d5ß H≤ p (Ø HFlushVol ° d ONLN d?ß æ≤ ◊ )v$A013 ° d ONLN dEß Í≤ Ô ),• "§ C "§ Dt "§ π "§ ∫* "§  "§ Ê7 "§ "§ M "§m §n§¸ "§˝ "• C "• π "•  "• "•m "•˝ ° d ONLN dJ¥ Hø f (º HGetVol ° d ONLN dT¥ æø ◊ )v$A014 "± C "± Dt "± π "± ∫* "±  "± Ê7 "± "± M "±m ±n±¸ "±˝ "≤ C "≤ π "≤  "≤ "≤m "≤˝ ° d ONLN d^¡ Hà f (… HSetVol ° d ONLN dh¡ æà ◊ )v$A015 "æ C "æ Dt "æ π "æ ∫* "æ  "æ Ê7 "æ "æ M "æm ænæ¸ "æ˝ "ø C "ø π "ø  "ø "øm "ø˝ ° d ONLN drŒ HŸ z (÷ H
FInitQueue ° d ONLN dÄŒ æŸ ◊ )v$A016 ° d ONLN dàŒrŸÂ )¥Never passed to foreign ° d ONLN d†⁄rÂ≥ *
file systems. "À C "À Dt "À π "À ∫* "À  "À Ê7 "À "À M "Àm ÀnÀ¸ "À˝ "à C "à π "à  "à "Ãm "Ã˝ ° d ONLN dØÁ HÚ a (Ô HEject ° d ONLN dµÁ æÚ ◊ )v$A017 ° d ONLN dªÁ ÍÚ Ô ),• "‰ C "‰ Dt "‰ π "‰ ∫* "‰  "‰ Ê7 "‰ "‰ M "‰m ‰n‰¸ "‰˝ " C " π "  " "Âm "½ ° d ONLN d¿Ù Hˇ k (¸ HGetFPos ° d ONLN d Ù æˇ ◊ )v$A018 ° d ONLN d–Ù Íˇ Ô ),• "Ò C "Ò Dt "Ò π "Ò ∫* "Ò Â "Ò Ê7 "Ò "Ò M "Òm ÒnÒ¸ "Ò˝ "Ú C "Ú π "Ú Â "Ú "Úm "Ú˝ ° d ONLN d’ H k ( HOffline ° d ONLN d› æ ◊ )v$A035 ° d ONLN d„ Í Ô ),• "˛ C "˛ Dt "˛ π "˛ ∫* "˛  "˛ Ê7 "˛ "˛ M "˛m ˛n˛¸ "˛˝ "ˇ C "ˇ π "ˇ  "ˇ "ˇm "ˇ˝ ° d ONLN dË H z ( H
SetFilLock ° d ONLN dÙ æ ◊ )v$A041 ° d ONLN d˙ Í Ô ),• " C " Dt " π " ∫* " Â " Ê7 " " M " m n ¸ " ˝ " C " π " Â " " m " ˝ ° d ONLN dˇ H& z (# H
RstFilLock ° d ONLN d æ& ◊ )v$A042 ° d ONLN d Í& Ô ),• " C " Dt " π " ∫* " Â " Ê7 " " M "m n¸ "˝ " C " π " Â " "m "˝ ° d ONLN d( H3 z (0 H
SetFilType ° d ONLN d"( æ3 ◊ )v$A043 ° d ONLN d(( Í3 Ô ),• ° d ONLN d+(r3Ù )àThis call is obsolete, but ° d ONLN dF4r?€ * it does get passed to ° d ONLN d\@rKÔ * foreign file systems. You ° d ONLN dvLrW * should return paramErr. "% C "% Dt "% π "% ∫* "%  "% Ê7 "% "% M "%m %n%¸ "%˝ "& C / "& π / "&  / "& / "&m / "&˝ / ° d ONLN dèY Hd k (a HSetFPos ° d ONLN dóY æd ◊ )v$A044 ° d ONLN dùY Íd Ô ),• "V C "V Dt "V π "V ∫* "V  "V Ê7 "V "V M "Vm VnV¸ "V˝ "W C "W π "W  "W "Wm "W˝ ° d ONLN d¢f Hq u (n H FlushFile ° d ONLN d¨f æq ◊ )v$A045 ° d ONLN d≤f Íq Ô ),• "c C "c Dt "c π "c ∫* "c  "c Ê7 "c "c M "cm cnc¸ "c˝ "d C "d π "d  "d "dm "d˝ ° d ONLN d∑s H~ ~ ({ H HFS Calls "p C "p Dt "p π "p ∫* "p  "p Ê7 "p "p M "pm pnp¸ "p˝ "q C "q π "q  "q "qm "q˝ ° d ONLN dΔÄ Hã a *
HOpen ° d ONLN dÃÄ æã ◊ )v$A200 ° d ONLN d“Ä Íã Ô ),• "} C "} Dt "} π "} ∫* "}  "} Ê7 "} "} M "}m }n}¸ "}˝ "~ C "~ π "~  "~ "~m "~˝ ° d ONLN d◊ç Hò u (ï H HGetVInfo ° d ONLN d·ç æò ◊ )v$A207 ° d ONLN dÁç Íò Ô ),• "ä C "ä Dt "ä π "ä ∫* "ä  "ä Ê7 "ä "ä M "äm änä¸ "ä˝ "ã C "ã π "ã  "ã "ãm "ã˝ ° d ONLN dÏö H• k (¢ HHCreate ° d ONLN dˆö æ• ◊ )v$A208 ° d ONLN d¸ö Í• Ô ),• "ó C "ó Dt "ó π "ó ∫* "ó  "ó Ê7 "ó "ó M "óm ónó¸ "ó˝ "ò C "ò π "ò  "ò "òm "ò˝ ° d ONLN dß H≤ k (Ø HHDelete ° d ONLN d ß æ≤ ◊ )v$A209 ° d ONLN dß Í≤ Ô ),• "§ C "§ Dt "§ π "§ ∫* "§  "§ Ê7 "§ "§ M "§m §n§¸ "§˝ "• C "• π "•  "• "•m "•˝ ° d ONLN d¥ Hø k (º HHOpenRF ° d ONLN d ¥ æø ◊ )v$A20A ° d ONLN d&¥ Íø Ô ),• "± C "± Dt "± π "± ∫* "±  "± Ê7 "± "± M "±m ±n±¸ "±˝ "≤ C "≤ π "≤  "≤ "≤m "≤˝ ° d ONLN d+¡ Hà k (… HHRename ° d ONLN d5¡ æà ◊ )v$A20B ° d ONLN d;¡ ÍÃ Ô ),• "æ C "æ Dt "æ π "æ ∫* "æ  "æ Ê7 "æ "æ M "æm ænæ¸ "æ˝ "ø C "ø π "ø  "ø "øm "ø˝
(Ú HC- ) 2 )$File System Routine Table ˇ d ˇ ˇˇˇˇ d
d , Times
. ( 3ûFile System Routine Table ,
Courier
° d ONLN d X ` c ú ( ` ` HGetFileInfo ° d ONLN d X ÷ c Ô )v$A20C ° d ONLN d X c ),• " U [ # " U \t " U — " U “* " U ˝ " U ˛7 " U6 " U7M " UÖ UÜ U " U # " V [ " V — " V ˝ " V6 " VÖ " V ° d ONLN d e ` p ú ( m ` HSetFileInfo ° d ONLN d ' e ÷ p Ô )v$A20D ° d ONLN d - e p ),• " b [ " b \t " b — " b “* " b ˝ " b ˛7 " b6 " b7M " bÖ bÜ b " b " c [ " c — " c ˝ " c6 " cÖ " c ° d ONLN d 2 r ` } ó ( z ` HUnmountVol ° d ONLN d > r ÷ } Ô )v$A20E ° d ONLN d D r } ),• ° d ONLN d G rä }Û )àWarning: reserved for ° d ONLN d ] ~ä â * system use only at system ° d ONLN d w ää ïÓ * shutdown or restart! ° d ONLN d å ñä ° * HUnmount unmounts a volume, ° d ONLN d ® ¢ä ≠ * even if files are open on ° d ONLN d ¬ Æä π˝ * the volume. The foreign ° d ONLN d ⁄ ∫ä ≈ * file system should flush ° d ONLN d Û Δä — * and close all open files ° d ONLN d “ä ›Û * before unmounting the ° d ONLN d" fiä È≠ * volume. " o [ " o \t " o — " o “* " o ˝ " o ˛7 " o6 " o7M " oÖ oÜ o " o " p [ w " p — w " p ˝ w " p6 w " pÖ w " p w ° d ONLN d+ Î ` ˆ ó ( Û ` AllocContig ° d ONLN d9 Î ÷ ˆ Ô )v$A210 ° d ONLN d? Î ˆ ),• " Ë [ " Ë \t " Ë — " Ë “* " Ë ˝ " Ë ˛7 " Ë6 " Ë7M " ËÖ ËÜ Ë " Ë " È [ " È — " È ˝ " È6 " ÈÖ " È ° d ONLN dD ¯ ` É ( `HGetVol ° d ONLN dN ¯ ÷ Ô )v$A214 " ı [ " ı \t " ı — " ı “* " ı ˝ " ı ˛7 " ı6 " ı7M " ıÖ ıÜ ı " ı " ˆ [ " ˆ — " ˆ ˝ " ˆ6 " ˆÖ " ˆ ° d ONLN dX ` É (
`HSetVol ° d ONLN db ÷ Ô )v$A215 " [ " \t " — " “* " ˝ " ˛7 "6 "7M "Ö Ü " " [ " — " ˝ "6 "Ö " ° d ONLN dl ` ç ( ` HSetFLock ° d ONLN dv ÷ Ô )v$A241 ° d ONLN d| ),• " [ " \t " — " “* " ˝ " ˛7 "6 "7M "Ö Ü " " [ " — " ˝ "6 "Ö " ° d ONLN dÅ `* ç (' ` HRstFLock ° d ONLN dã ÷* Ô )v$A242 ° d ONLN dë * ),• " [ " \t " — " “* " ˝ " ˛7 " 6 " 7M " Ö Ü " " [ " — " ˝ " 6 " Ö " ° d ONLN dñ, `7 Ã (4 `HFS Dispatch Calls ") [ ") \t ") — ") “* ") ˝ ") ˛7 ")6 ")7M ")Ö )Ü) ") "* [ "* — "* ˝ "*6 "*Ö "* ° d ONLN dÆ9 `D ~ *
DTGetPath ° d ONLN d€J æU ◊ )v$0020 ° d ONLN d‚J#Ui )ebHasDesktopMgr ° d ONLN dÒJrU )OThe returned ioDTRefNum ° d ONLN d VraÍ * must be a file reference ° d ONLN d"brm€ * number (a FCB must be ° d ONLN d8nryê * used). "G C "G Dt "G π "G ∫* "G  "G Ê7 "G "G M "Gm GnG¸ "G˝ "H C / "H π / "H  / "H / "Hm / "H˝ / ° d ONLN d@{ HÜ (É H DTCloseDown ° d ONLN dL{ æÜ ◊ )v$0021 ° d ONLN dS{#Üi )ebHasDesktopMgr "x C "x Dt "x π "x ∫* "x  "x Ê7 "x "x M "xm xnx¸ "x˝ "y C "y π "y  "y "ym "y˝ ° d ONLN ddà Hì u (ê H DTAddIcon ° d ONLN doà æì ◊ )v$0022 ° d ONLN dvà#ìi )ebHasDesktopMgr "Ö C "Ö Dt "Ö π "Ö ∫* "Ö Â "Ö Ê7 "Ö "Ö M "Öm ÖnÖ¸ "Ö˝ "Ü C "Ü π "Ü Â "Ü "Üm "Ü˝ ° d ONLN dáï H† u (ù H DTGetIcon ° d ONLN díï æ† ◊ )v$0023 ° d ONLN dôï#†i )ebHasDesktopMgr "í C "í Dt "í π "í ∫* "í  "í Ê7 "í "í M "ím íní¸ "í˝ "ì C "ì π "ì  "ì "ìm "ì˝ ° d ONLN d™¢ H≠ â (™ H
DTGetIconInfo ° d ONLN dπ¢ æ≠ ◊ )v$0024 ° d ONLN d¿¢#≠i )ebHasDesktopMgr "ü C "ü Dt "ü π "ü ∫* "ü  "ü Ê7 "ü "ü M "üm ünü¸ "ü˝ "† C "† π "†  "† "†m "†˝ ° d ONLN d—Ø H∫ u (∑ H DTAddAPPL ° d ONLN d‹Ø æ∫ ◊ )v$0025 ° d ONLN d„Ø#∫i )ebHasDesktopMgr "¨ C "¨ Dt "¨ π "¨ ∫* "¨  "¨ Ê7 "¨ "¨ M "¨m ¨n¨¸ "¨˝ "≠ C "≠ π "≠  "≠ "≠m "≠˝ ° d ONLN dÙº H« Ñ (ƒ H DTRemoveAPPL ° d ONLN dº æ« ◊ )v$0026 ° d ONLN dº#«i )ebHasDesktopMgr "π C "π Dt "π π "π ∫* "π  "π Ê7 "π "π M "πm πnπ¸ "π˝ "∫ C "∫ π "∫  "∫ "∫m "∫˝ ° d ONLN d… H‘ u (— H DTGetAPPL ° d ONLN d$… æ‘ ◊ )v$0027 ° d ONLN d+…#‘i )ebHasDesktopMgr "Δ C "Δ Dt "Δ π "Δ ∫* "Δ Â "Δ Ê7 "Δ "Δ M "Δm ΔnΔ¸ "Δ˝ "« C "« π "«  "« "«m "«˝ ° d ONLN d<÷ H· Ñ (fi H DTSetComment ° d ONLN dI÷ æ· ◊ )v$0028 ° d ONLN dP÷#·i )ebHasDesktopMgr "” C "” Dt "” π "” ∫* "”  "” Ê7 "” "” M "”m ”n”¸ "”˝ "‘ C "‘ π "‘  "‘ "‘m "‘˝ ° d ONLN da„ HÓ ì (Î HDTRemoveComment ° d ONLN dq„ æÓ ◊ )v$0029 ° d ONLN dx„#Ói )ebHasDesktopMgr "‡ C "‡ Dt "‡ π "‡ ∫* "‡  "‡ Ê7 "‡ "‡ M "‡m ‡n‡¸ "‡˝ "· C "· π "·  "· "·m "·˝ ° d ONLN dâ H˚ Ñ (¯ H DTGetComment ° d ONLN dñ æ˚ ◊ )v$002A ° d ONLN dù#˚i )ebHasDesktopMgr "Ì C "Ì Dt "Ì π "Ì ∫* "Ì Â "Ì Ê7 "Ì "Ì M "Ìm Ìn̸ "Ì˝ "Ó C "Ó π "Ó Â "Ó "Óm "Ó˝ ° d ONLN dÆ˝ H k ( HDTFlush ° d ONLN d∂˝ æ ◊ )v$002B ° d ONLN dΩ˝#i )ebHasDesktopMgr ° d ONLN dÃ˝r€ )ODo nothing (noErr) on ° d ONLN d‚ r‡ * remote shared volumes. "˙ C "˙ Dt "˙ π "˙ ∫* "˙  "˙ Ê7 "˙ "˙ M "˙m ˙n˙¸ "˙˝ "˚ C "˚ π "˚  "˚ "˚m "˚˝ ° d ONLN d˙ H! k ( HDTReset ° d ONLN d æ! ◊ )v$002C ° d ONLN d #!i )ebHasDesktopMgr ° d ONLN dr!€ )ODo nothing (noErr) on ° d ONLN d."r-‡ * remote shared volumes. " C " Dt " π " ∫* "  " Ê7 " " M "m n¸ "˝ " C " π "  " "m "˝ ° d ONLN dF/ H: u (7 H DTGetInfo ° d ONLN dQ/ æ: ◊ )v$002D ° d ONLN dX/#:i )ebHasDesktopMgr ° d ONLN dg/r:Ô )OReturn paramErr on remote ° d ONLN dÅ;rFΩ * shared volumes. ", C ", Dt ", π ", ∫* ",  ", Ê7 ", ", M ",m ,n,¸ ",˝ "- C "- π "-  "- "-m "-˝ ° d ONLN díH HS Ñ (P H DTOpenInform ° d ONLN düH æS ◊ )v$002E ° d ONLN d¶H#Si )ebHasDesktopMgr ° d ONLN dµHrS )OThe returned ioDTRefNum ° d ONLN dÕTr_Í * must be a file reference ° d ONLN dÊ`rk€ * number (a FCB must be ° d ONLN d¸lrwÔ * used). Return paramErr on ° d ONLN dxrɇ * remote shared volumes. "E C "E Dt "E π "E ∫* "E  "E Ê7 "E "E M "Em EnE¸ "E˝ "F C ; "F π ; "F  ; "F ; "Fm ; "F˝ ; ° d ONLN d.Ö Hê p (ç HDTDelete ° d ONLN d7Ö æê ◊ )v$002F ° d ONLN d>Ö#êi )ebHasDesktopMgr ° d ONLN dMÖrêÔ )OReturn paramErr on remote ° d ONLN dgërúΩ * shared volumes. "Ç C "Ç Dt "Ç π "Ç ∫* "Ç Â "Ç Ê7 "Ç "Ç M "Çm ÇnǸ "Ç˝ "É C "õ C # "õ Dt "É π "õ π "õ ∫* "É Â "õ  "õ Ê7 "É "õ "õ M "Ém "õm õnõ¸ "É˝ "õ˝ #
(Ú HC- ) 4 )$File System Routine Table ˇ2 d ˇ ˇˇˇˇ d
d , Times
. ( 3ûFile System Routine Table ,
Courier
° d ONLN d d ` o ¿ ( l `AppleShare Calls " a [ # " a \t " a — " a “* " a ˝ " a ˛7 " a6 " a7M " aÖ aÜ a " a # " b [ " b — " b ˝ " b6 " bÖ " b ° d ONLN d q ` | ó *
(ÚoFile System Routine Table )öC- ) 5 ˇ d ˇ ˇˇˇˇ d
d , Helvetica
. ° d ONLN d V ` h ‹ +`d APPENDIX D: ° d ONLN d V h÷ )êFILE SYSTEM MANAGER Q ^ Q ° d ONLN d l ~¯ *QUESTIONS AND ANSWERS ~ ^ ~ , Times
(ÚD- ) 1 ˇ
t d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager , Helvetica
° d ONLN d U H d ˆ *-ABOUT THIS APPENDIX N F N g F g
° d ONLN d ~ H ä *'ZThis appendix contains a bunch of questions and answers gathered by Developer Support that ° d ONLN d o ä H ñ; * 5will be useful to developers of foreign file systems.
° d ONLN d • ª H *3QUESTIONS AND ANSWERS ¥ F ¥ Õ F Õ
° d ONLN d ª ‰ T ] + 'Q ° d ONLN d º ‰ ] ` ) : ° d ONLN d æ ‰ f › ) MIf my foreign file system doesn’t support one of the non-required HFSDispatch ° d ONLN d f ¸ * $select codes, what should it return? ° d ONLN d1 T ] ( TA ° d ONLN d2 ] ` ) : ° d ONLN d4 f‡ ) QThe foreign file system should return paramErr (-50) if it doesn’t support one of ° d ONLN dÜ f&6 * *the non-required HFSDispatch select codes. ° d ONLN d≤D TP ] (M TQ ° d ONLN d≥D ]P ` ) : ° d ONLN dµD fPØ ) BI’m implementing the Desktop Manager calls. How big can icons get? ° d ONLN d¯b Tn ] (k TA ° d ONLN d˘b ]n ` ) : ° d ONLN d˚b fn› ) LApple’s Desktop Manager allows icons to be up to 4500 bytes, you should too. ° d ONLN dIå Tò ] (ï TQ ° d ONLN dJå ]ò ` ) : ° d ONLN dLå fò≈ ) IWhat fields in an FCBRec can be used by a foreign file system for its own ° d ONLN dñò f§ ñ * purposes? ° d ONLN d†∂ T¬ ] (ø TA ° d ONLN d°∂ ]¬ ` ) : ° d ONLN d£∂ f¬‰ ) PSee Chapter 3, The File System Utility Routines, of the Guide to the File System ° d ONLN dÙ¬ fŒÈ * SManager. It tells what fields can be used by your foreign file system and tells how ° d ONLN dHŒ f⁄: * -those fields are used by the HFS file system. ° d ONLN dw¯ T ] ( TQ ° d ONLN dx¯ ] ` ) : ° d ONLN dz¯ f„ ) JWhat are the catalog node ID (CNID) numbers below fsUsrCNID (16) used for? ° d ONLN d≈ T" ] ( TA ° d ONLN dΔ ]" ` ) : ° d ONLN d» f"„ ) OCNID 1 is reserved for the parent ID of the root directory (fsRtParID) and CNID ° d ONLN d" f.Õ * M2 is reserved for the directory ID of the root directory (fsRtDirID). On HFS ° d ONLN df. f: * Vvolumes, 3 is used for the extents file, 4 is used for the catalog file, and 5 is used ° d ONLN dΩ: fFΔ * Kfor the bad allocation block file. Your foreign file system can use CNIDs 5 ° d ONLN d F fR2 * *through 15 for whatever purposes it needs. ° d ONLN d5^ fj“ *KWhen _UnmountVol is called, the File Manager checks to see if there are any ° d ONLN dÅj fv¬ * Gopen files on that volume with a file number (fcbFlNm in the FCBRec) of ° d ONLN d…v fÇfl * LfsUsrCNID or greater. If so, the File Manager does not pass the _UnmountVol ° d ONLN dÇ féà * Mrequest on to the file system that owns the volume and a result of fBsyErr is ° d ONLN ddé fö· * Oreturned to the caller. You can use CNIDs 5 through 15 for files opened by your ° d ONLN d¥ö f¶⁄ * Lforeign file system that should not prevent _UnmountVol from succeeding (for ° d ONLN d¶ f≤Δ * Eexample, you should use a CNID below fsUsrCNID for the file number in ° d ONLN dG≤ fæÁ * IFCBRecs used for the Desktop Manager DTGetPath or DTOpenInform routines). (Ú HD- ) 2 )$Questions and Answers ˇº d ˇ ˇˇˇˇ d
. +H3 Guide to the File System Manager ° d ONLN d U T a ] + +Q ° d ONLN d U ] a ` ) : ° d ONLN d U f a‹ ) LWe do not necessarily want full AppleShare (AFP) access-control, but we need ° d ONLN d P a f mS * 2more information on foreign file privilege models. ° d ONLN d É T ã ] ( à TA ° d ONLN d Ñ ] ã ` ) : ° d ONLN d Ü f ㉠) MTo be compatible with existing Macintosh applications, you must mimic the HFS ° d ONLN d ‘ ã f óµ * Efile system's permission model. Inside Macintosh: Files describes how ° d ONLN d ó f £Õ * IAppleShare does that on pages 2-17 and 2-18. If you want a more extensive ° d ONLN dd £ f ØË * Ppermission model that AppleShare-aware applications can use, then you'll need to ° d ONLN dµ Ø f ª≤ * Asupport the AppleShare HFSDispatch selectors and mimic AppleShare ° d ONLN d˜ ª f «Ÿ * Mpermissions. If you can't fit into the AppleShare model, you can come up with ° d ONLN dE « f ”ª * Ayour own model and use PBGetForeignPrivs and PBSetForeignPrivs to ° d ONLN dá ” f fl‡ * Omanipulate your native privileges. However, you still must map those privileges ° d ONLN d◊ fl f Î… * Hto the HFS file system model. If you decide to use PBGetForeignPrivs and ° d ONLN d Î f ˜À * LPBSetForeignPrivs, you'll use the creator type assigned to your foreign file ° d ONLN dm ˜ f± * Asystem for your vMForeignPrivID number (the number you return for ° d ONLN dØ f * PBHGetVolParms requests). ° d ONLN d - T9 ] (6 TQ ° d ONLN dÀ- ]9 ` ) : ° d ONLN dÕ- f9ú ) @What is needed for a foreign file system to support PBCatSearch? ° d ONLN dK TW ] (T TA ° d ONLN dK ]W ` ) : ° d ONLN dK fW≈ ) GYou'll need to support PBHGetVolParms so that you can indicate that you ° d ONLN dYW fcË * Ssupport CatSearch. It will be up to your foreign file system to come up with a fast ° d ONLN d≠c fo– * Iway to search a volume’s catalog for matches. The Apple Developer Support ° d ONLN d˜o f{ * Osample code MoreFiles version 1.2 and later contains much of the code needed to ° d ONLN dG{ fá, * )implement CatSearch in the file Search.C. ° d ONLN dr• T± ] (Æ TQ ° d ONLN ds• ]± ` ) : ° d ONLN du• f±Á ) KFindFolder seems to make some assumption on volumes that support AppleShare ° d ONLN d¡± fΩQ * 0(AFP) access-control. What are those assuptions? ° d ONLN dÚœ T€ ] (ÿ TA ° d ONLN dÛœ ]€ ` ) : ° d ONLN dıœ f€fi ) PThe folder manager assumes that user ID 0 is the guest user and user ID 1 is the ° d ONLN dF€ fÁ⁄ * Oadministrator (owner) user and uses byte range locks on an empty data file as a ° d ONLN dñÁ fÛfl * Osemaphore to control access to individual trash folders on the volume. For more ° d ONLN dÊÛ fˇ * Jinformation, see Inside AppleTalk, second edition and the AppleTalk Filing ° d ONLN d1ˇ f ´ * CProtocol Version 2.1 chapter of the AppleShare 3.0 Developer’s Kit. ° d ONLN dv) T5 ] (2 TQ ° d ONLN dw) ]5 ` ) : ° d ONLN dy) f5@ ) )How should I handle VolumeMount requests? ° d ONLN d£G TS ] (P TA ° d ONLN d§G ]S ` ) : ° d ONLN d¶G fS◊ ) JVolumeMount requests are caught by the File System Manager before they are ° d ONLN dÒS f_¡ * Jpassed to the File Manager. FSM calls each installed foreign file system’s ° d ONLN d<_ fk÷ * HfileSystemCommProc with a ffsIDVolMountMessage. If the media type is not ° d ONLN dÖk fw› * Pyour foreign file system’s media type, you return extFSErr. If the media type is ° d ONLN d÷w fÉÊ * Nyour foreign file system’s media type, you return noErr and the your HFSCIProc ° d ONLN d %É fèN * 0will be called with the VolumeMount select code. ° d ONLN d Wõ fßË *LWhen your HFSCIProc is called with the VolumeMount select code, your foreign ° d ONLN d §ß f≥≥ * Efile system should do everything needed to mount a volume. It should: (Ú HD- ) 4 )$Questions and Answers ˇ ∏ d ˇ ˇˇˇˇ d
return noErr. ° d ONLN d• l± u (Æ lQ ° d ONLN dÊ• u± x ) : ° d ONLN dË• ~±˝ ) QCan I put up an additional user authentication dialog when my foreign file system ° d ONLN d:± ~Ω
* gets a VolumeMount request? ° d ONLN dVœ l€ u (ÿ lA ° d ONLN dWœ u€ x ) : ° d ONLN dYœ ~€¯ ) PYou put up an additional user authentication dialog if the caller of VolumeMount ° d ONLN d™€ ~Á * Ytells you it is safe to do that. To allow foreign file system to determine if it is safe, ° d ONLN dÁ ~Û˘ * MApple has extended the VolMountInfoHeader record to include a flags word (the ° d ONLN dRÛ ~ˇÿ * Fsame flags word already in the AFPVolMountInfo record). By setting the ° d ONLN dôˇ ~ ˚ * UvolMountInteractBit (bit 15) in the flags word, the caller can tell your foreign file ° d ONLN dÔ ~ * Nsystem that it is safe to use the Dialog Manager to put up your authentication ° d ONLN d> ~#ˇ * Sdialog. In addition, if your foreign file system finds that the VolMountInfo record ° d ONLN dí# ~/˘ * Ppassed is usable but needs to be updated, it can set the volMountChangedBit (bit ° d ONLN d„/ ~;Ï * Q14) in the flags word to tell the caller that it needs to update the VolMountInfo ° d ONLN d5; ~GÛ * Grecord using the PBGetVolMountInfoSize and PBGetVolMountInfo functions. ° d ONLN d~S ~_’ *HThe Alias Manager has been updated to set the volMountInteractBit if the ° d ONLN d«_ ~kı * NkARMNoUI rule is passed to the MatchAlias function, and to return the state of ° d ONLN dk ~wŸ * Ethe volMountChangedBit in the needsUpdate parameter of the MatchAlias ° d ONLN d\w ~ɪ * @function and the wasChanged parameter the ResolveAlias function. ° d ONLN dûè ~õ§ *>Here are the new constant definitions and data types you need: +˛ZQuestions and Answers )çD- ) 5 ˇ " d ˇ ˇˇˇˇ d
d , Times
. +H3 Guide to the File System Manager ,
Courier
° d ONLN d i r u2 +*? /* The new volume mount flags */ ° d ONLN d ! u r Å ñ * enum { ° d ONLN d ) Å Ü ç + volMountInteractBit = 15, ° d ONLN d C ÅD çÊ )æ/* Input to VolumeMount: If ° d ONLN d d çV ôÏ + set, it's OK for the file ° d ONLN d É ôV •⁄ * system to perform user ° d ONLN d ü •V ±Ê * interaction to mount the ° d ONLN d Ω ±V Ωå * volume */ ° d ONLN d » Ω Ü …: ( Δ Ü volMountInteractMask = 0x8000, ° d ONLN d È ’ Ü · *volMountChangedBit = 14, ° d ONLN d ’D ·Ú )æ /* Output from VoumeMount: If ° d ONLN d% ·V Ì˛ + set, the volume was mounted, ° d ONLN dG ÌV ˘‡ * but the volume mounting ° d ONLN dd ˘V¯ * information record needs to ° d ONLN dÖV™ * be updated. */ ° d ONLN dï Ü 4 ( Ü volMountChangedMask = 0x4000, ° d ONLN dµ) Ü5Ù *=volMountFSReservedMask = 0x00ff, /* bits 0-7 are defined each ° d ONLN d¯5VAŒ +– file system's use */ ° d ONLN dA ÜM˙ (J Ü>volMountSysReservedMask = 0xff00 /* bits 8-15 are reserved for ° d ONLN dRMVY» +– Apple system use */ ° d ONLN dfY re ~ (b r}; ° d ONLN djq r}V *&/* The new volume mount info record */ ° d ONLN dë} râ * struct VolMountInfoHeader { ° d ONLN dÆâ Üï § + short ° d ONLN d¥â ÿï )Rlength; ° d ONLN dºâDï‡ )l/* length of location data ° d ONLN d‹ïV°» + (including self) */ ° d ONLN dÒ° Ü≠ ¬ (™ Ü
VolumeType ° d ONLN d¸° ÿ≠ ¸ )Rmedia; ° d ONLN d°D≠Ê )l/* type of media. Variable ° d ONLN d$≠Vπ⁄ + length data follows */ ° d ONLN d<π Ü≈ § (¬ Üshort ° d ONLN dBπ ÿ≈ ¸ )Rflags; ° d ONLN dIπD≈Ü )l /* flags */ ° d ONLN dU≈ r— ~ (Œ r}; ° d ONLN dX— r›∞ * 5typedef struct VolMountInfoHeader VolMountInfoHeader; ° d ONLN dé› rÈz * ,typedef VolMountInfoHeader *VolMountInfoPtr;
° d ONLN dª T ] ( TQ ° d ONLN dº ] ` ) : ° d ONLN dæ f Ÿ ) PWhat is the correct time to put up an additional user authentication dialog when ° d ONLN d f*_ * 2my foreign file system gets a VolumeMount request? ° d ONLN dB< TH ] (E TA ° d ONLN dC< ]H ` ) : ° d ONLN dE< fH⁄ ) PThe correct time to put up an additional user authentication dialog is when your ° d ONLN dñH fTÈ * Kforeign file system’s fileSystemCommProc gets the ffsIDVolMountMessage. You ° d ONLN d‚T f`‚ * Qdon’t want to wait until your HFSCIProc is called because at that time, you’re in ° d ONLN d4` fl“ * Lthe middle of a File Manager request and cannot do anything that might cause ° d ONLN dÅl fx Û * another File Manager request. (Ú HD- ) 6 )$Questions and Answers ˇ
ú d ˇ ˇˇˇˇ d
d , Times
. ( 3´Questions and Answers ° d ONLN d a l m u ( j lQ ° d ONLN d a u m x ) : ° d ONLN d a ~ m„ ) HHow do I register a VolumeMount media type? How do I register a foreign ° d ONLN d L m ~ y Á * privileges ID number? ° d ONLN d b ã l ó u ( î lA ° d ONLN d c ã u ó x ) : ° d ONLN d e ã ~ óÛ ) LUse your file system ID number for your foreign privileges ID number and use ° d ONLN d ≤ ó ~ £ÿ * Kthe creator type that you registered for your file system ID number for the ° d ONLN d ˛ £ ~ Ø * GVolumMount media type. If for some reason, you need another VolumeMount ° d ONLN dF Ø ~ ª˜ * Pmedia type or foreign privileges ID number, you can simply register another file ° d ONLN dó ª ~ «¸ * Nsystem ID number. It will be up to you to document your file system ID number, ° d ONLN dÊ « ~ ”’ * Dforeign privileges ID number, and VolumeMount media type if you want ° d ONLN d+ ” ~ flÙ * Ldevelopers to know about them. That’s keeping with Apple’s policy of keeping ° d ONLN dx fl ~ ÎÍ * Kcreator types, card ID numbers, ADEV ID numbers, etc. confidential. If you ° d ONLN dƒ Î ~ ˜Û * Odecide to publish information specific to your file system, you should probably ° d ONLN d ˜ ~Ô * Kinclude header files for programmers and that’s where you can document your ° d ONLN d` ~ ´ * numbers. ° d ONLN dj- l9 u (6 lQ ° d ONLN dk- u9 x ) : ° d ONLN dm- ~9˘ ) QWhere are the constants for the new information I can get by calling Gestalt with ° d ONLN dø9 ~E ˘ * the gestaltFSAttr selector? ° d ONLN d€W lc u (` lA ° d ONLN d‹W uc x ) : ° d ONLN dfiW ~c ≤ ) Right here: ,
Courier
° d ONLN dÎ~ ää + 'gestaltFSAttr = 'fs ', ° d ONLN d~\ä )“ /* file system attributes */ ° d ONLN d!ñ ä¢J (ü ä gestaltFullExtFSDispatching = 0, ° d ONLN dBñ\¢ )“ /* all HFSDispatch selectors ° d ONLN dd¢nÆ
+ are passed through to file ° d ONLN dÑÆn∫™ *
systems */ ° d ONLN dè∫ äΔ& (√ ägestaltHasFSSpecCalls = 1, ° d ONLN d™∫\Δ¯ )“/* File Manager has FSSpec ° d ONLN d Δn“û + calls */ ° d ONLN d”“ äfiJ (€ ä gestaltHasFileSystemManager = 2, ° d ONLN dÙ“\fi‡ )“/* has the File System ° d ONLN dfinÍ™ +
Manager */ ° d ONLN dÍ äˆ> (Û ä gestaltFSMDoesDynamicLoad = 3, ° d ONLN d:Í\ˆ )“ /* File System Manager supports ° d ONLN d_ˆn⁄ + dynamic loading */ ° d ONLN dr ä8 ( ä gestaltFSSupports4GBVols = 4, ° d ONLN dê\Ê )“/* file system supports ° d ONLN d≠nÏ + 4 gigabyte volumes */ ° d ONLN d√ ä&8 (# ä gestaltFSSupports2TBVols = 5, ° d ONLN d·\&Ê )“/* file system supports ° d ONLN d˛&n2Ï + 2 terabyte volumes */ ° d ONLN d2 ä>D (; ä gestaltHasExtendedDiskInit = 6, ° d ONLN d42\>‘ )“/* has extended Disk ° d ONLN dN>nJ¯ + Initialization calls */
vMVolumeGrade ° d ONLN dqY e )û3The relative speed rating of the volume. The scale ° d ONLN d®e q„ * +used to determine these values is currently ° d ONLN d◊q }˘ * 2uncalibrated, so until further notice, return 0 in ° d ONLN d
} âI * this field. (Ú HD- ) 8 )$Questions and Answers ˇ6 d ˇ ˇˇˇˇ d
Ò l ˝ } + $Bit ° d ONLN d Ò ñ ˝ ∂ )*Name ° d ONLN d Ò4 ˝d )ûMeaning ° d ONLN d l x ( l31 ° d ONLN d! ñ — )*
bLimitFCBs ° d ONLN d, 4 )û,The volume supports a small finite number of ° d ONLN d\4! * 7open files. Set this bit to indicate that applications ° d ONLN dó!4- * 0should attempt to limit the number of files they ° d ONLN dÀ-49 * +keep open on this volume. For example, the ° d ONLN d˙94E
* /Finder limits the number of file control blocks ° d ONLN d-E4Q" * 5used during copying to 8 instead of 16 if this bit is ° d ONLN dfQ4]E * set. ° d ONLN dk] li x (f l30 ° d ONLN dn] ñi ” )* bLocalWList ° d ONLN dz]4i )û3Set this bit to indicate that the vMLocalHand field ° d ONLN d±i4u * 0of the GetVolParmsInfoBuffer record is valid and ° d ONLN dÂu4Å * 0the Finder’s open window list information is not ° d ONLN dÅ4ç# * 1stored on this volume. Shared volumes should set ° d ONLN dNç4ôX * this bit. ° d ONLN dXô l• x (¢ l29 ° d ONLN d[ô ñ• ÿ )* bNoMiniFndr ° d ONLN dgô4•∞ )ûReserved; always set to 1. ° d ONLN dÇ• l± x (Æ l28 ° d ONLN dÖ• ñ± œ )* bNoVNEdit ° d ONLN dè•4±¸ )û(This volume’s name cannot be edited. The ° d ONLN dª±4Ω * -System 7 Finder ignores this bit and looks at ° d ONLN dÏΩ4…Ê * $bAccessCntl instead for some reason. ° d ONLN d… l’ x (“ l27 ° d ONLN d… ñ’ “ )*
bNoLclSync ° d ONLN d …4’ )û3Set this bit to indicate that modification dates on ° d ONLN dV’4· * /this volume can change with no action from this ° d ONLN dâ·4Ìˇ * (system. For example, a network volume’s ° d ONLN dµÌ4˘≈ * modification dates can change. ° d ONLN d‘˘ l x ( l26 ° d ONLN d◊˘ ñ ◊ )* bTrshOffLine ° d ONLN d‰˘4 )û2Set this bit to indicate that this volume does not ° d ONLN d4 * 1support an offline state. The PBOffLine function ° d ONLN dO4 * /is not supported by this volume. If the Finder ° d ONLN dÇ 4)# * 4finds this volume offline, it is zoomed to the Trash ° d ONLN d∫)45Å * and unmounted. ° d ONLN d…5 lA x (> l25 ° d ONLN dÃ5 ñA Ÿ )* bNoSwitchTo ° d ONLN dÿ54A )û/Obsolete. The Finder will not switch launch to ° d ONLN d A4M» * any application on this volume. ° d ONLN d+M lY ä (V l24–21 ° d ONLN d2M4Y† )»Reserved. Set to zero. ° d ONLN dJY le x (b l20 ° d ONLN dMY ñe › )* bNoDeskItems ° d ONLN dZY4e )û2Set this bit to indicate that this volume does not ° d ONLN dêe4q" * 2support objects on the desktop.If the volume has a ° d ONLN dΔq4}# * 3folder named Desktop Folder in it’s root directory, ° d ONLN d˝}4â‘ * %it is treated as any other directory. ° d ONLN d#â lï x (í l19 ° d ONLN d&â ñï ÿ )* bNoBootBlks ° d ONLN d2â4ï )û2Set this bit to indicate that this volume is not a ° d ONLN dhï4°˜ * (startup volume. The Startup menu item is ° d ONLN dî°4≠ * 0disabled. Boot blocks are not copied during copy ° d ONLN d»≠4πi * operations. +H<Questions and Answers )çD- ) 9 ˇŒ d ˇ ˇˇˇˇ d
bHasShortName ° d ONLN dÛ· Ì )û-This volume supports AFP short names with the ° d ONLN d$Ì ˘ˇ * .GetXCatInfo select code ($3A). Once again, the ° d ONLN dV˘ ¶ * bit name isn’t really accurate. ° d ONLN dv T ` ( T10 ° d ONLN dy ~ Œ )*bHasFolderLock ° d ONLN dà ‡ )û$This volume supports PBHSetFLock and ° d ONLN d∞ * /PBHRstFLock on folders. A locked folder cannot ° d ONLN d„ )á * be deleted or renamed. ° d ONLN d˙) T5 Z (2 T9 ° d ONLN d¸) ~5 )* bHasPersonalAccessPrivileges ° d ONLN d) 5Ê )û+This volume has local file sharing enabled. ° d ONLN dE5 TA Z (> T8 ° d ONLN dG5 ~A fl )*bHasUserGroupList ° d ONLN dY5 AÚ )û0The user and group list of the local file server ° d ONLN dçA M * /returned by the PBGetUGEntry function are valid ° d ONLN d¿M Yh * for this volume. ° d ONLN d—Y Te Z (b T7 ° d ONLN d”Y ~e « )*
bHasCatSearch ° d ONLN d·Y e )û.This volume supports the PBCatSearch function. ° d ONLN de Tq Z (n T6 ° d ONLN de ~q ∫ )* bHasFileIDs ° d ONLN d e q„ )û*This volume supports the file ID reference ° d ONLN dLq }„ * (functions, including the PBExchangeFiles ° d ONLN dx} âG * function. ° d ONLN dÇâ Tï Z (í T5 ° d ONLN dÑâ ~ï ƒ )* bHasBtreeMgr ° d ONLN dëâ ïµ )û Reserved for internal Apple use. ° d ONLN d≤ï T° Z (û T4 ° d ONLN d¥ï ~° )*bHasBlankAccessPrivileges ° d ONLN dŒï °È )û)This volume supports inherited AFP access ° d ONLN d˚° ≠É * privileges for folders. ° d ONLN d ≠ Tπ f (∂ T3–0 ° d ONLN d ≠ π¢ )» Reserved. Set them to zero. (Ú HD- ) 10 )$Questions and Answers ˇÏ d ˇ ˇˇˇˇ d
d , Times
. ( 3´Questions and Answers ° d ONLN d U l a u ( ^ lQ ° d ONLN d U u a x ) : ° d ONLN d U ~ a˛ ) OCan I write a native Power PC foreign file system with the File System Manager? ° d ONLN d S s l u ( | lA ° d ONLN d T s u x ) : ° d ONLN d V s ~ ) MWe do not recommend writing File System Manager-based foreign file systems in ° d ONLN d § ~ ãÔ * Gnative Power PC code because there would be a minimum of two mixed mode ° d ONLN d Ï ã ~ ó˘ * Oswitches per file system request you handle (you’ll be called from emulated 68K ° d ONLN d< ó ~ £Í * Mcode). Complex file system requests that cause multiple driver requests could ° d ONLN dä £ ~ Ø * Ncause many more mixed mode switches. If you think of a place where native code ° d ONLN dŸ Ø ~ ª˜ * Pwould really help the performance of your file system, you’d be best off putting ° d ONLN d* ª ~ « * Ojust that code in a Power PC accelerated code resource and calling it from your ° d ONLN dz « ~ ”Î * Kforeign file system (which would still be mostly in 68K code) only when you ° d ONLN dΔ ” ~ fl ° * need it. (Ú|Questions and Answers )áD- ) 11 ˇ
